Sentinel Cloud Services - Run-time Guidedocumentation.sentinelcloud.com/3.5/PDF/Sentinel Cloud...TableofContents Preface xii Chapter1:Overview 1 1.1.WhyUseSentinelCloudServices? 2

Sentinel Cloud V.3.5Run-time Guide

Software Version

This documentation is applicable for Sentinel Cloud Run-time version 3.5, released with Sentinel Cloud3.5.

Document Revision History

Part Number 007-012137-001, Revision H

DocumentRevision

Change Date

A Sentinel Cloud 3.0 release. New features include:

n Tamper Detection in usage logs in On-premisemode

December 2012

B Sentinel Cloud 3.1 release. New features include:

n Server authentication with Public CA certificate and clientauthentication with message signing.

April 2013

C Sentinel Cloud 3.2 release. New features include:

n Introduced on-premise licensing for client applications

June 2013

D Sentinel Cloud 3.3 release. New features include:

n Modified the workflow of on-premise licensing for serverapplications.

n The on-premise licensing for client applications madeavailable in Java and .NET interfaces.

n A new optional parameter, Capacity, introduced in thelogin API.

September 2013

E Sentinel Cloud 3.3 release with on-premise support on Linux October 2013

F Sentinel Cloud 3.4 release December 2013

G Beta release for Sentinel Cloud 3.5. Added support for isolatednetworks.

April 2014

H Sentinel Cloud 3.5 release. June 2014

Disclaimer and Copyrights

Copyright © 2014, SafeNet, Inc. All rights reserved.

http://www.safenet-inc.com/

We have attempted to make these documents complete, accurate, and useful, but we cannotguarantee them to be perfect. When we discover errors or omissions, or they are brought to ourattention, we endeavor to correct them in succeeding releases of the product.

http://www.safenet-inc.com/

iii Sentinel Cloud Run-time Guide

SafeNet® and Sentinel® are registered trademarks of SafeNet, Inc. All other product names referencedherein are trademarks or registered trademarks of their respectivemanufacturers.

Table of Contents

Preface xii

Chapter 1: Overview 1

1.1. Why Use Sentinel Cloud Services? 21.2. Sentinel Cloud Components 31.2.1. Sentinel Cloud Run-time 41.2.2. Sentinel Cloud Connect 41.2.3. Sentinel EMS 51.2.4. Sentinel Cloud Directory Services 61.2.5. Sentinel Cloud Data Engine 61.2.6. Sentinel Cloud Connect Web Services 6

1.3. Sentinel Cloud On-premise Deployment 71.3.1. Introduction 71.3.2. On-premise Feature Caching Modes 71.3.3. On-premise Entitlement Level Licensing 81.3.4. On-premise Feature Level Licensing 171.3.5. Comparing On-premise Feature Caching Modes 22

1.4. Comparing Cloud Run-time, On-premise Run-time, and Cloud Connect Web Services 231.5. Secure Communication Using Certificates and Message Signing 251.5.1. SSL Based Communication 251.5.2. Server Authentication Using Public CA Certificates 261.5.3. Client Authentication Using Message Signing 26

1.6. Compatibility and Support 26

Chapter 2: Cloud Run-time APIs 27

2.1. API Usage Guidelines 282.2. acquireLicenseClient 292.2.1. Description 292.2.2. Setting Run-time Configuration Properties 292.2.3. API Calling Sequence 292.2.4. acquireLicenseClient (Java) 302.2.5. acquireLicenseClient (.NET) 312.2.6. scr_acquireLicenseClient (C) 33

2.3. getIdentity 352.3.1. Description 352.3.2. Workflow 352.3.3. API Calling Sequence 372.3.4. getIdentity (Java) 37

v Sentinel Cloud Run-time Guide

2.3.5. getIdentity (.NET) 392.3.6. scr_getIdentity(C) 40

2.4. transfer 422.4.1. API Calling Sequence 432.4.2. transfer (Java) 432.4.3. transfer (.NET) 462.4.4. scr_transfer (C) 49

2.5. getInfo 522.5.1. Description 522.5.2. Workflow 532.5.3. When to use the getInfo API? 542.5.4. When NOT to use the getInfo API? 562.5.5. API Calling Sequence 572.5.6. getInfo (Java) 572.5.7. getInfo (.NET) 592.5.8. scr_getInfo (C) 60

2.6. login 622.6.1. Description 622.6.2. API Calling Sequence 632.6.3. Additional Information for Cloud Deployment 632.6.4. Additional Information for On-Premise Deployment 652.6.5. Consumption Order 672.6.6. login (Java) 672.6.7. login (.NET) 682.6.8. scr_login (C) 70

2.7. refreshSession 722.7.1. Description 732.7.2. Usage Notes 732.7.3. API Calling Sequence 732.7.4. refreshSession (Java) 742.7.5. refreshSession (.Net) 742.7.6. scr_refreshSession (C) 75

2.8. logout 762.8.1. Description 762.8.2. API Calling Sequence 772.8.3. logout (Java) 772.8.4. logout (.NET) 782.8.5. scr_logout (C) 79

2.9. releaseLicenseClient 802.9.1. Description 802.9.2. API Calling Sequence 812.9.3. releaseLicenseClient (Java) 812.9.4. releaseLicenseClient (.NET) 812.9.5. scr_releaseLicenseClient(C) 82

vi

Chapter 3: Classes/Structures 85

3.1. LicenseRuntime 863.2. FeatureNode 873.2.1. The SaaSFeatureNode Class (Java) 883.2.2. The SaaSFeatureNode Class (.NET) 893.2.3. scr_FeatureNode_t (C) 91

3.3. Format 913.3.1. The Format Class (Java) 933.3.2. The Format Class (.NET) 943.3.3. scr_Format_t (C) 95

3.4. Scope 963.4.1. The Scope Class (Java) 973.4.2. The Scope Class (.NET) 993.4.3. scr_Scope_t (C) 101

3.5. Entitlement 1033.5.1. The Entitlement Class (Java) 1043.5.2. The Entitlement Class (.NET) 1043.5.3. scr_Entitlement_t (C) 105

3.6. LicenseAttribute 1053.6.1. The LicenseAttribute Class (Java) 1093.6.2. The LicenseAttribute Class (.NET) 1093.6.3. scr_LicenseAttribute_t (C) 110

3.7. Product 1103.7.1. The Product Class (Java) 1113.7.2. The Product Class (.NET) 1113.7.3. scr_Product_t (C) 112

3.8. Feature 1123.8.1. The Feature Class (Java) 1133.8.2. The Feature Class (.NET) 1143.8.3. scr_Feature_t (C) 115

3.9. License 1163.9.1. The License Class (Java) 1173.9.2. The License Class (.NET) 1173.9.3. scr_License_t (C) 118

3.10. Concurrency 1183.10.1. The Concurrency Class (Java) 1193.10.2. The Concurrency Class (.NET) 1203.10.3. scr_Concurrency_t (C) 121

3.11. GetInfoOptionalParam 1213.11.1. The GetInfoOptionalParam Class (Java) 1223.11.2. The GetInfoOptionalParam Class (.NET) 1223.11.3. scr_GetInfoOptionalParam_t (C) 122

3.12. GetInfoResponse 123

vii Sentinel Cloud Run-time Guide

3.12.1. The GetInfoResponse Class (Java) 1243.12.2. The GetInfoResponse Class (.NET) 1253.12.3. scr_GetInfoResponse_t (C) 125

3.13. Attributes 1263.13.1. The Attributes Class (Java) 1283.13.2. The Attributes Class (.NET) 1293.13.3. scr_Attributes_t (C) 129

3.14. LoginOptionalParam 1303.14.1. The LoginOptionalParam Class (Java) 1313.14.2. The LoginOptionalParam Class (.NET) 1313.14.3. scr_LoginOptionalParam_t (C) 132

3.15. LoginResponse 1333.15.1. The LoginResponse Class (Java) 1343.15.2. The LoginResponse Class (.NET) 1353.15.3. scr_LoginResponse_t (C) 136

3.16. LogoutOptionalParam 1373.16.1. The LogoutOptionalParam Class (Java) 1383.16.2. The LogoutOptionalParam Class (.NET) 1383.16.3. scr_LogoutOptionalParam_t (C) 138

3.17. LogoutResponse 1393.17.1. The LogoutResponse Class (Java) 1403.17.2. The LogoutResponse Class (.NET) 1403.17.3. scr_LogoutResponse_t (C) 141

3.18. RefreshSessionOptionalParam 1413.18.1. The RefreshSessionOptionalParam Class (Java) 1423.18.2. The RefreshSessionOptionalParam Class (.Net) 1423.18.3. scr_RefreshSessionOptionalParam_t (C) 142

3.19. RefreshSessionResponse 1423.19.1. The RefreshSessionResponse Class (Java) 1433.19.2. The RefreshSessionResponse Class (.Net) 1433.19.3. scr_RefreshSessionResponse_t (C) 143

3.20. GetIdentityOptionalParam 1443.20.1. The GetIdentityOptionalParam Class (Java) 1453.20.2. The GetIdentityOptionalParam Class (.NET) 1453.20.3. scr_GetIdentityOptionalParam_t (C) 145

3.21. GetIdentityResponse 1453.21.1. The GetIdentityResponse Class (Java) 1463.21.2. The GetIdentityResponse Class (.NET) 1463.21.3. scr_GetIdentityResponse_t (C) 147

3.22. TransferOptionalParam 1473.22.1. The TransferOptionalParam Class (Java) 1483.22.2. The TransferOptionalParam Class (.NET) 1493.22.3. scr_TransferOptionalParam_t 150

3.23. TransferResponse 150

viii

3.23.1. The TransferResponse Class (Java) 1513.23.2. The TransferResponse Class (.NET) 1513.23.3. scr_TransferResponse_t (C) 151

3.24. Features 1513.24.1. scr_Features_t (C) 152

3.25. AcquireClientOptionalParam 1523.25.1. The AcquireClientOptionalParam Class (Java) 1533.25.2. The AcquireClientOptionalParam Class (.Net) 1533.25.3. scr_AcquireClientOptionalParam_t (C) 153

3.26. The AcquireClientResponse Class 1533.26.1. The AcquireClientResponse Class (Java) 1543.26.2. The AcquireClientResponse Class (.Net) 1543.26.3. scr_AcquireClientResponse_t (C) 154

3.27. Configuration 1543.27.1. The Configuration Class (Java) 1553.27.2. The Configuration Class (.NET) 1563.27.3. scr_Configuration_t (C) 158

3.28. LicenseException 1593.28.1. The LicenseException Class (Java) 1603.28.2. The LicenseException Class (.NET) 161

Chapter 4: Enumerations (C) 163

4.1. scr_Count_t (C) 1644.1.1. Members 164

4.2. scr_FormatType_t (C) 1644.2.1. Members 164

4.3. scr_Action_t 1654.3.1. Members 165

Chapter 5: Sample Code of Cloud Run-time APIs 167

5.1. Sample Code - acquireLicenseClient 1685.1.1. Sample Code - acquireLicenseClient (Java) 1695.1.2. Sample Code - acquireLicenseClient (.NET) 1695.1.3. Sample Code - scr_acquireLicenseClient (C) 170

5.2. Sample Code - getIdentity 1715.2.1. Sample Code - getIdentity (Java) 1725.2.2. Sample Code - getIdentity (.NET) 1725.2.3. Sample Code - getIdentity (C) 173

5.3. Sample Code - transfer 1755.3.1. Sample Code - transfer (Java) 1765.3.2. Sample Code - transfer (.NET) 1775.3.3. Sample Code - scr_transfer (C) 178

ix Sentinel Cloud Run-time Guide

5.4. Sample Code - getInfo 1795.4.1. Sample Code - getInfo (Java) 1805.4.2. Sample Code - getInfo (.NET) 1835.4.3. Sample Code - scr_getInfo (C) 187

5.5. Sample Code - login 1935.5.1. Sample Code - login (Java) 1945.5.2. Sample Code - login (.NET) 1955.5.3. Sample Code - scr_login (C) 197

5.6. Sample Code - refreshSession 1985.6.1. Sample Code - refreshSession (Java) 1995.6.2. Sample Code - refreshSession (.NET) 2005.6.3. Sample Code - scr_refreshSession(C) 200

5.7. Sample Code - logout 2015.7.1. Sample Code - logout (Java) 2025.7.2. Sample Code - logout (.NET) 2035.7.3. Sample Code - scr_logout (C) 203

5.8. Sample Code - releaseLicenseClient 2055.8.1. Sample Code - releaseLicenseClient (Java) 2065.8.2. Sample Code - releaseLicenseClient (.NET) 2065.8.3. Sample Code - scr_releaseLicenseClient (C) 206

Chapter 6: Integrating Cloud Run-time APIs 207

6.1. Specific Requirements 2086.1.1. Specific Requirements (Java) 2096.1.2. Specific Requirements (.NET) 2106.1.3. Specific Requirements (C) 210

6.2. Integration Steps 2126.2.1. Integrating Cloud Run-time APIs (Java) 2136.2.2. Integrating Cloud Run-time APIs (.NET) 2146.2.3. Integrating Cloud Run-time APIs (C) 214

6.3. Best Practices 2166.3.1. Plan an Authorization Strategy 2166.3.2. Keep an Optimal Cache Size 2166.3.3. Set Optimal Time to Transfer Usage Logs 216

Appendix A: Client Configuration File 217

A.1. List of Configuration Properties 217A.2. Configuration Properties Details 220A.2.1. Directory Server Configuration 220A.2.2. General Configuration 220A.2.3. Proxy Settings 221A.2.4. Logging Settings 222

x

A.2.5. Advanced Properties 223A.2.6. Security Configuration 224A.2.7. Cloud Connect Configuration 224A.2.8. .NET Specific Configurations 224

A.3. Name and Location of the Client Configuration File 226A.3.1. Defining a Custom Path for Configuration File 226

A.4. Proxy Configuration 226

Appendix B: Troubleshooting 229

B.1. No Server Mapped to the Given Vendor ID (1001) 229B.2. Unable to Initialize Run-time Library (1003) 229B.3. Internal Error or Internal System Error (1009) 229B.4. Error RT_ERR_INVALID_COOKIE (1016) 229B.5. Error in Detaching Licenses by Using the transfer API (1021) 230B.6. Abnormal Application Termination on Linux (1025) 230B.7. Connection to the Cloud Directory Services Failed (2001) 230B.8. Communication Error (2001 to 2012) 230B.9. Error RT_ERR_INVALID_AUTHENTICATION (2011) 231B.10. Problem in Loading Configuration File (2501) 231B.11. Error RT_ERR_NO_AUTH_SESSION (-14007) 232B.12. Error RT_ERR_INVALID_FINGERPRINT (-14008) 232B.13. Error RT_ERR_INVALID_CUSTOM_CRITERIA (-14020 ) 232B.14. Problem in integrating Sentinel Cloud due to .NET Version 232

Appendix C: Error Codes 235

C.1. Error Codes (Java) 236C.2. Error Codes (.NET) 238C.3. Error Codes (C) 240C.4. Obsolete Error Codes 244

Appendix D: Build Dependencies 245

Appendix E: Caching (Cloud Deployment) 248

E.1. Overview 248E.2. Description 248E.3. Cache Configuration in Run-time 249E.4. Cache configuration in Cloud Connect 250E.5. More about Caching Behavior 250

xi Sentinel Cloud Run-time Guide

Appendix F: Handling of Abandoned Sessions 252

F.1. Cloud Licensing 252F.1.1. Configurations 252F.1.2. Examples 253F.1.3. Guidelines on Setting Configurations 254

F.2. On-premise Licensing 256F.2.1. Configuration Settings 256F.2.2. Examples 258F.2.3. Guidelines on Setting Configurations 259

Appendix G: Capacity 262

Appendix H: Glossary 268

PrefaceThank you for choosing the Sentinel Cloud Services—the robust licensing and entitlementsmanagement solution for your SaaS applications hosted in the cloud.

About This Document

This document is meant for the developers who want to use Sentinel Cloud Services for licensing theirCloud and On-premise applications. This document contains:

n Product Overview

n Product Components

n Sentinel Cloud Run-time Classes/Structures and APIs

n Sentinel Cloud Run-time (Client) Configuration File

Conventions Used in This Guide

Convention Description

Bold lettering Denotes keystrokes, menu items, window names or fields.Courier Denotes syntax, prompts, and code examples.

Italic lettering Denotes file names and directory names. Else, used for emphasis.

Documentation Resources

Visit our documentation portal: documentation.sentinelcloud.com.

Obtaining Support

If you encounter a problem while installing, registering or operating this product, pleasemake surethat you have read the documentation. If you cannot resolve the issue, contact your supplier orSafeNet Customer Support. SafeNet Customer Support operates 24 hours a day, 7 days a week. Yourlevel of access to this service is governed by the support plan arrangements made between SafeNetand your organization. Please consult this support plan for further information about yourentitlements, including the hours when telephone support is available to you.

Contact Method Contact Information

Address SafeNet, Inc.4690Millennium DriveBelcamp, Maryland 21017, USA

http://documentation.sentinelcloud.com/

xiii Sentinel Cloud Run-time Guide

Contact Method Contact Information

Phone US 1-800-545-6608

International 1-410-931-7520

Technical SupportCustomer Portal

https://serviceportal.safenet-inc.comExisting customers with a Technical Support Customer Portal account canlog in to manage incidents, get the latest software upgrades, and access theSafeNet Knowledge Base

Documentation Feedback

To help us improve future versions of Sentinel Cloud Services documentation, wewant to know aboutany corrections, clarifications or further information you would find useful. When you contact us,please include the following information:

n The title, part number, and version of the guide you are referring to

n The version of the product you are using

n Your name, company name, job title, phone number, and e-mail ID

Send us e-mail at: [email protected]

Thank you for your feedback.

https://serviceportal.safenet-inc.com/

mailto:[email protected]?subject=<Product Name>Documentation Feedback

Chapter 1:Overview

Sentinel® Cloud Services is a license and entitlement management solution by SafeNet for your SaaSand on-premise applications. For the latest information on Sentinel Cloud Services, seewww.sentinelcloud.com.

This section provides an overview of product benefits and product components.

1.1. Why Use Sentinel Cloud Services? 2

1.2. Sentinel Cloud Components 3

1.3. Sentinel Cloud On-premise Deployment 7

1.4. Comparing Cloud Run-time, On-premise Run-time, and Cloud Connect Web Services 23

1.5. Secure Communication Using Certificates and Message Signing 25

1.6. Compatibility and Support 26

1

http://www.sentinelcloud.com/

2 Chapter 1: Overview

1.1. Why Use Sentinel Cloud Services?This section provides a list of product features that you can use to license your SaaS and on-premiseapplications.

Feature Based Authorization

Sentinel Cloud enables you to authorize user access at the feature level. With feature-level control,you can easily define granularity of access to your offering and allow customers to optimize how theyconsume the application. You can create a product to allow the customers use the entire applicationor a group of features. This flexibility allows you to bundle features in different sets and create avariety of products, meeting the requirements of a wide range of customers.

Innovative License Models

Sentinel Cloud Services provides a flexible framework supporting a rich array of licensemodels,enabling you to utilize a wide variety of business controls.You can leverage a variety of optionsranging from simple subscription to complex usage-based models to license your application. Thisenables you to maximize return on investment through greater product versatility and broad marketreach.

Entitlement Management and Provisioning

You can create entitlements for your products, and provision the entitlements using a web interface.

Usage Based Billing

Sentinel Cloud simplifies your billing process management by providing automated metering andexport of usage data for billing. It provides detailed usage tracking and reporting features that enableyou to analyze data and identify trends in order to improve business decision-making capabilities, andinstantly respond to emerging market opportunities.

Segregated Design and Delivery

After you have carried out the simple, one-time process of integrating the Sentinel Cloud hostedsolution with your application, your product management and delivery tasks get totally segregatedfrom your product design and development tasks, empowering you to choose from a wide range oflicensemodels without affecting the design and development of the product.

On-premise and Cloud Support

Sentinel Cloud Run-time provides a common set of APIs that enable you to deploy your applicationson-premise and on cloud without any change in application source code.

1.2. Sentinel Cloud ComponentsThe diagram below shows interaction between the various components of the Sentinel CloudServices:

The following are the components:

n Sentinel Cloud Run-time

n Sentinel Cloud Connect

n Sentinel EMS

n Sentinel Cloud Directory Services

n Sentinel Cloud Data Engine

n Sentinel Cloud Connect Web Services

See Also:

n Client Configuration File

n Secure Communication Using Certificates and Message Signing



1.2.1. Sentinel Cloud Run-time

It is a client-side component that interacts with Cloud-enabled components (Cloud Connect andDirectory Services), for authorization of licensing decisions and collection of usage data. Sentinel CloudRun-time provides a set of API calls that you need to insert in your application code to query rights fora user to each individual feature. The tasks that Sentinel Cloud Run-time performs are:

n User authorization: Allows or restricts a user from accessing the features of your application,as defined by the service agreement and the governing licensemodel. Sentinel Cloud Run-time communicates with Cloud Connect for licensing decisions.

Sentinel Cloud Run-time does not facilitate user authentication. You need toauthenticate the user prior to requesting authorization. However in the case of on-premise feature level deployment, you can perform authentication by integrating anauthentication system with Sentinel Cloud.

n Usage data collection: Collects data related to usage of your application by each user, at thefeature level. This data can be further leveraged by billing and business intelligence systems.Sentinel Cloud Run-time stores this data locally and periodically transfers it to the SentinelCloud Connect for metering and data aggregation purposes.

Quick Characteristics

n A set of API calls to be integrated in your application source code

n Can be deployed on cloud and on-premise

n Stateless APIs for licensing applications hosted on Cloud. It means the Cloud Run-timeinstance can be replaced during downtime.

The on-premise licensing is not stateless.

n Run-time can run in a load balanced server farm for the purpose of scaling. You can integrateRun-timewith a web application deployed in a distributed environment, wheremultipleCloud Connect instances run behind a load balancer.

n Light-weight and has a small footprint

n Communicates with Sentinel Cloud Connect and Directory Services server over HTTPS

n Available for Java, .NET, and C platforms

You can use Sentinel Cloud Services for applications written in other languages, byimplementing Sentinel Cloud Connect Web Services.

n Uses the Unicode encoding to provide support for multiple languages. This enables all Run-time APIs to support internationalization. You can provide data in any language to the APIs.

1.2.2. Sentinel Cloud Connect

It is a SafeNet-hosted component that authorizes license requests and processes usage recordsreceived from Sentinel Cloud Run-time.

License enforcement is achieved when Sentinel Cloud Run-time, integrated in your application,queries Sentinel Cloud Connect for a license-serving decision, when your user attempts to use afeature of your application. Both the components interact with each other using predefined request-responsemessages.

This component is also responsible for activating the user service agreement, enforcing licensingterms, and global decision making.


n Managed by SafeNet

n Cloud-ready

n Stateless - Replaceable instances in case an instance goes down

n Scalable - Can be clustered

n Supports internationalization

1.2.3. Sentinel EMS

Sentinel EMS is a web-based management platform that helps in service catalog definition, licenseprovisioning and management, reporting functions, and customer management. It provides both—aweb-based interface and a web services interface—for creating and maintaining entitlements.

For information about EMS web portal, refer to EMS User's Guide. For information aboutEMS web services, refer to EMS Web Services Guide.

Functions of EMS are:

n Helps define product catalog and license models at the feature-level to boost product ver-satility and business agility.

n Provides role-based vendor portal for easily creating, implementing, and managing users,roles, and privileges.

n Provides a self-service portal for end users wherein they can directly view usage data andmanage users (in an enterprise).

n Provides a reporting interface to keep track of customer data usage and license con-sumption.



n Cloud-ready

n Can be accessed by a web portal or can be directly integrated in your existing back office sys-tems by using web service calls.



1.2.4. Sentinel Cloud Directory Services

It is a SafeNet-hosted component that helps connect a Run-time instance to a Cloud Connect node. Itsfunctions are:

n Maintains and manages a list of Run-time instances and Cloud Connect nodes.

n Authenticates Cloud Connect nodes and Cloud Run-times when they initialize.

n Sends the information of the registered Cloud Connect nodes to Cloud Run-times on request.After a positive response is received from Directory Services, Run-time sends all furtherrequests to Cloud Connect for license consumption and usage data upload.



n Cloud-ready

n Stateless - Replaceable instances in case an instance goes down

n Scalable - Can be clustered

1.2.5. Sentinel Cloud Data Engine

The Data Engine stores, processes, and aggregates usage records of your application. This data is usedby Sentinel EMS for processing usage and billing reports.



n Cloud-ready

1.2.6. Sentinel Cloud Connect Web Services

Sentinel Cloud Connect Web Services expose licensing and monetization abilities of Sentinel Cloud fordirect use in an ISV application. These web services enable you to integrate Sentinel Cloud inapplications that run on platforms not supported by Sentinel Cloud Run-time.

For information on Cloud Connect web services, see Cloud Connect Web Services Guide.


n Platform-independent

n Flexible, provides more control, and offers easy integration with an ISV application.

n License agnostic in nature

n Supports internationalization

1.3. Sentinel Cloud On-premise Deployment

1.3.1. Introduction

Sentinel Cloud offers a hybrid licensing solution that allows software providers to protect theirapplications both on-premise and on cloud. It means that you can deliver your application as a serviceon the Cloud as well as you can install it within the premises of your enterprise customer. The keycharacteristic is that whichever deployment model you choose, the source code of your applicationremains identical.

Sentinel Cloud On-premise deployment mode supports protected applications that reside within thecustomer’s premises—on a customer-owned machine. This is in contrast to Sentinel Cloud SaaSdeployment where the protected application is expected to be hosted on a Server residing in Cloud,that is under the control of the software provider.

In both types of deployment, the protected application has a component integrated, Sentinel CloudRun-time, which communicates with hosted components of Sentinel Cloud Service – DirectoryServices, Cloud Connect, and EMS. A common set of Run-time APIs is used for licensing an application.This enables the software provider to write a single application that can be deployed on-premise aswell as on cloud.

1.3.2. On-premise Feature Caching Modes

For on-premise deployment, the Feature Caching Mode specifies how licenses are enforced, wherelicenses are stored, and how is concurrency managed (locally or globally). Following options forFeature Caching Mode are available:

n Entitlement Level: Here, an application pulls an entitlement to local machine before licensescan be consumed.

In this mode, the application pulls the entire entitlement to themachine and licenseenforcement happens locally. This mode allows software vendors to create a strict bindingbetween the end machine and the entitlement that it is authorized to access. Softwarevendors can control howmany machines can have the active entitlement at any given pointof time and can also authorize who can access the entitlement. This mode also providesflexibility of creating unique licenses for each machine or a set ofmachines. A request foraccessing a feature by the application is authorized locally, without transferring to CloudConnect, based on the pulled entitlement.

Entire license enforcement happens locally including concurrency which is particularly usefulin server mode applications. Usage collected is shared with Cloud Connect periodically ifconnectivity is available.

Entitlement Level mode also enables vendors to generate licenses for machines that neverconnect to the Internet and in turn are unable to connect with hosted Sentinel Cloud servicecomponents.

n Feature Level: Here, an application explicitly requests the required features.



This type of on-premise licensing is primarily meant for applications running on clientmachines. The rights/licenses of a particular user are fetched from Cloud Connect and cachedlocally. A license request is fulfilled by Run-time either from local cache or by fetching it fromCloud Connect, if the license is not already present in local cache. A license is cached locallyeither at the time of first request for that license or explicitly when the application detachesthe license from Cloud Connect for a specified interval of time.

Since licenses for only the requested features are fetched to an on-premisemachine based on auser identity, this type of licensing is called as Feature Level licensing.

You can use a machine for only one type of on-premise deployment, either entitlement levelor feature level. These two types of on-premise deployments are not supported.

1.3.3. On-premise Entitlement Level Licensing

The following are the basic steps involved in provisioning and generating licenses for on-premiseentitlement level:

1. Entitlement Creation

a. In EMS, an entitlement is created with Deployment Type as On-Premise and FeatureLevel Caching mode as Entitlement Level, for enterprise customers.

b. ADetach Interval is set in the entitlement that specifies themaximum duration, in hour(s), for which the entitlement can be detached. The default value is 2160 hours. You canenter a value in the range of 1-43800 hours (approximately 5 years). The default and max-imum allowed values of this parameter are configurable and you can get them changedby contacting SafeNet Support. The Detach Interval can also be set as No Limit indic-ating that the license can be detached for an indefinite duration, as might be required inthe case of isolated machines.

See section Detach Interval for information on how the actual detach interval isdetermined.

c. A Station Count is set in the entitlement that specifies themaximum number ofmachines that can detach (consume) an entitlement at any given point of time fromSentinel Cloud Connect. For details, see About Station Count.

d. The usage collection can be enabled or disabled for on-premisemachines.

The entitlement is provisioned on Sentinel Cloud Connect.

2. Machine and Entitlement Registration

The on-premisemachines (on which the protected application will run)must be registered withthe entitlement (from which the licenses will be served) in the Cloud Connect. It is a mandatory,one-time step.

SeeMachine and Entitlement Registration (Mandatory) for details.

3. Application Installation at Customer's Site

The ISV's customer installs the application that has Sentinel Cloud Run-time integrated in it,and starts the application.

4. License Retrieval

When the application runs, Run-time connects to Cloud Connect to retrieve the initial licensesslice.

a. To fetch a new license, the application must call the transfer API with NULL value for theuser. The duration for which a license is detached is specified in the Interval parameter ofthe transfer API.

See section Detach Interval for information on how the actual detach interval isdetermined.

b. Cloud Connect generates licenses for all the features provisioned in the entitlement thatmachine is registered with.

c. Run-time fetches licenses and installs them in a local license store.

d. To refresh existing licenses, the application needs to call the transfer API periodically forthe given entitlement. For example, once in a day with detach interval of 30 days; indic-ating that the application can work without connecting to Cloud Connect for 30 dayssince the last disconnect.

e. With licenses residing in a persistent memory, the on-premisemachine can remain dis-connected from Cloud Connect and still have licenses to serve for a maximum duration,as specified by the detach inetrval.

5. License Usage

Once licenses are available, you can call the login and logout APIs for consuming features.

6. Usage Collection

The usage data is collected for an entitlement depending on whether the usage collection hasbeen enabled or disabled during entitlement creation in EMS.

Please see section Workflow for Isolated Machines for exact steps on how licenses aregenerated for an isolated on-premisemachine.

Main Features

Themain features of the on-premise entitlement level licensing support are:

n Application Hosted in Enterprise Environment: This mode is suitable for applications thatare expected to be hosted within the control of an enterprise customer.

n Time-limited License Served to On-premise Machine: The on-premise Run-time linked to theISV application connects with Sentinel Cloud Connect, fetches time-limited licenses, anddeploys them in a license store on the on-premisemachine. When an enterprise useraccesses the application, the required licenses are served from the local license store. Thelocal licenses can be refreshed by the Run-time by calling the transfer API.



n On-premise Persistent License Store: The licenses deployed on the on-premisemachine arestored in a persistent memory, and work well across disconnects and reboots. Thus you cancontinue to use the application offline for the duration specified by the interval parameter ofthe transfer API.

n On-premise Provisioning: To support on-premise licensing, an entitlement is created in EMSspecifically for on-premise consumption. An entitlement created for on-premise can only beconsumed from the on-premise applications and not through Cloud, and vice versa.

Only enterprise unnamed licensing is supported for on-premise. The licensemodels that canbe used for creating on-premise entitlements created for entitlement level licensing are:

o Subscription

o Postpaid

o Concurrent with Per Login counting type

The on-premise entitlements meant for server deployment are created in EMS withEntitlement Level option selected. While creating such entitlements, the followinginformation is also specified:

o Maximum number of on-premisemachines on which a license can be detached sim-ultaneously is specified as Station Count.

o Number of hours for which the entitlement can be detached is specified as DetachInterval.

o Usage data collection is enabled or disabled for on-premisemachines.

n Licenses Locked to Registered On-premise Machines: The licenses are tied to specific on-premisemachines (and are stored in local license store of on-premise Run-time). Before anentitlement (or corresponding licenses) can be served to on-premisemachines, themachinesmust be registered with Cloud Connect. Refer to Machine and Entitlement Registration(Mandatory) for details.

n Persistent Usage Store: The usage data is logged by the on-premise Run-time in a temporarymemory area of small size called cache. When the cache size reaches its limit, the usage datais transferred from cache to a persistent store (physical disk), where from the data is syncedwith Cloud Connect at regular intervals. The persistent store ensures recovery of usageinformation in cases ofmachine reboot and network failure.

However, if an application crashes before the usage data is transferred from cache to physicaldisk, the small chunk of usage data stored in cache is lost and cannot be recovered.

You can disable the usage cache if you want the records to be stored directly to persistentdisk. To disable the usage cache, set the InMemoryUsageCount property to 0 in theconfiguration parameter of the acquireLicenseClient API.

The usage log files are stored in encrypted format to ensure security. The location of usage logfiles can be specified in theUsagePath property of the client configuration file.

Run-time attempts to synch usage data with Cloud Connect periodically after aspecified interval called State Sync Time.

n Isolated Machine Support: Isolated on-premisemachines are those which are neverconnected to the Internet. For isolated machines, you need to create entitlements withEntitlement Level feature caching mode. See section Workflow for Isolated Machines fordetails.

Machine and Entitlement Registration (Mandatory)

In on-premise entitlement level licensing, the licenses are tied to specific on-premisemachines and arestored in local license store of on-premise Run-time. Before an entitlement (or corresponding licenses)can be served to on-premisemachines, themachines must be registered with Cloud Connect.

Machine registration means binding a machine with a specific entitlement, for which the uniqueidentification information of a machine needs to be registered with a particular entitlement with thehelp of EMS web service.

Steps in machine registration are:

1. (One-time step) Deciding the criteria that you want to use for machine identification andregistration.

2. Obtaining unique identification information (fingerprint, host name, or both) of a machine.

3. Calling EMS web service to register themachine identification information with a specificentitlement in Cloud Connect.

Points to note:

n Amachine cannot be registered with multiple entitlements, however an entitlement can beregistered with multiple machines.

n You can register any number ofmachines for an entitlement; but at a time themaximum num-ber ofmachines on which an entitlement can be detached is controlled by the Station Countvalue specified in EMS.

Deciding Machine Registration Criteria (One-time step)

The information for identifying a machine uniquely can be: fingerprint (hardware characteristics),host name, or both. You need to choose the preferred way ofmachine identification and get itconfigured by contacting SafeNet Support.

You can choose to register machines based on the following information that identifies a machineuniquely:

RegistrationCriteria

Description Remarks

Fingerprint(hardwarecharacteristics)

Fingerprint is mandatory and hostname is optional for registration.

Use this criteria if you want strong bindingbetween application and hardwarecharacteristics of themachine on whichlicense are to be served.Note that the application may not run inexceptional cases when registration getsfailed due to particular machine hardware.

Host Name Host Name is mandatory and Use this criteria if you do not want to bind



RegistrationCriteria

Description Remarks

fingerprint is optional forregistration.

application with hardware characteristics of amachine.Note that the application may bemisused byend-users if same host name is used formultiple machines.

Fallback Fingerprint is mandatory and hostname is optional for registration.This is the default registrationcriteria.

This is a combination of the above two andprovides strong binding with fallbackmechanism. Primarily, fingerprint is used forbinding. But if required hardwarecharacteristics are not present in fingerprint,then host name is used for binding, ifprovided.

The criteria used for registration (fingerprint, host name, or both) should be unique for the customer.

It is recommended not to get the registration criteria changed till the licenses are in use. Thecriteria should only be changed after logout or returning the detached licenses.

Obtaining Machine Identification Information

This section describes how to obtain machine identification information: fingerprint and host name.

Obta ining Fingerpr int

To obtain machine fingerprint, Sentinel Cloud Run-timemust be installed on customer’s machinesand the Sentinel Local License Manager service should be running.

n Method 1 (Recommended)

To retrievemachine fingerprint, call the getInfo Run-time API with theMACHINE_FINGERPRINT format type.

The output is an XML containing machine fingerprint.

n Method 2 (Deprecated)

This method of obtaining fingerprint has been deprecated. It is recommended to use themethod 1 described above which is direct and simple to implement.

To obtain fingerprint, the application can call the hasp_get_info() function with the followingformat and scope parameters:

format = <?xml version="1.0" encoding="UTF-8" ?><haspformat

format="host_fingerprint"/>

Scope = <?xml version="1.0" encoding="UTF-8" ?><haspscope><license_manager host-

name="localhost"/></haspscope>

The output is an XML containing machine fingerprint.

Please note that the hasp_get_info() function is available only for the C interface.

Obta ining Host Name

You can use the standard Windows functions for obtaining host name.

n For Windows, use theGetComputerName API. Visit http://msdn.microsoft.com/en-us/library/windows/desktop/ms724295%28v=vs.85%29.aspx for details.

n For Linux, use the gethostname function. Visit http://linux.die.net/man/2/gethostname fordetails.

Calling EMS Web Service for Machine, Entitlement Registration

After creating an entitlement for customer and obtaining machine identification information(fingerprint, host name, or both), you need to call the EMS web service Add Entitlement Fingerprintfor registration. This registers machine(s) against the given EID.

One EID can be registered with multiple machines. This means that an entitlement can be sharedamong multiple machines. However on a machine, the application can consume only one entitlement.

For details about web services available for machine registration, please see EMS Web Services Guide.

About Station Count

Themaximum number of host machines (stations) on which an entitlement can be detached isdefined in EMS, as station count. You can register any number ofmachines for an entitlement, but ata time only the number ofmachines specified by station count can consume the entitlement. Itmeans that you might have registered 10machines but if station count is 5, you can consumeentitlement on only 5machines. The value of station count ranges from 1 to 50.

The station count is released in the following ways:

n By canceling a detached license from a host machine. For this, you need to call the transferAPI with CANCEL_DETACH action.

n By a background process that checks for the Detach interval defined for a machine, andreleases it after the interval elapses.

You can increase or decrease the station count by reconfiguring an entitlement.

To serve a new detach request, the number ofmachines on which licenses have been detachedshould be less then themaximum station count.

Example 1

Suppose Station Count is 3.

Machines M1, M2, and M3 have already detached licenses.

Another machineM4will get an error on requesting a detach license, as maximum allowed stationshave already detached the licenses. The request from M4will be served only when a station gets free,which is possible if:

n Any of themachines M1, M2, or M3 cancels the detached license, or

n The background process releases a station after the detach interval has elapsed.

Example 2


http://msdn.microsoft.com/en-us/library/windows/desktop/ms724295(v=vs.85).aspx

http://msdn.microsoft.com/en-us/library/windows/desktop/ms724295(v=vs.85).aspx

http://linux.die.net/man/2/gethostname


Let us assume again that the station count is set to 3 and 3 stations have already detached anentitlement.

If station count is now reduced to 2 by reconfiguring the entitlement, any detach requests (even fromthe existing stations) will be declined.

The number of current stations in use need to be reduced to a value less than the new station countto allow further detach requests. This can be done by canceling a detached license, or by waiting forthe background process to release the station after the elapsed interval.

Workflow for Isolated Machines

Sentinel Cloud provides the ability to detach licenses from Cloud Connect for machines that operate inIsolated Networks and never connect to the Internet. Licenses for the target machines are detachedfrom Cloud Connect by a separatemachine that has connectivity to Cloud Connect. The obtainedlicenses are transferred to the isolated machine (by a method defined by the customer) and deployedthere with the help of Run-time API calls.

The support for isolated networks is provided with entitlements where feature caching mode is set toEntitlement Level.

The steps of obtaining licenses for isolated machines are given below.

In these steps, the isolated machine refers to the on-premisemachine which is neverconnected to the Internet. The connected machine refers to the on-premisemachine that isalways/occasionally connected to the Internet.

Steps

Registration (Mandatory, one-time step)

1. The isolated machine retrieves themachine fingerprint. For this, the getInfo API is called withtheMACHINE_FINGERPRINT(8) format type.

Sentinel Cloud Run-timemust be installed and the Sentinel Local License Managerservice should be running on the isolated machine before calling Run-time APIs.

2. The isolated machine provides themachine fingerprint to the connected machine. The end userdecides how to send the fingerprint, for example, by using a USB dongle, over intranet, or byany other method.

3. The connected machine registers themachine with Cloud Connect by calling EMS web service.

License Retrieval by Connected Machine

4. The isolated machine determines the current license state by calling the getInfo API with theCURRENT_LICENSE_STATE(16) format type.



5. The current license state is sent from isolated machine to connected machine. The end userdecides how to send the license state, for example, by using a USB dongle, over intranet, or byany other method.

6. The connected machine requests licenses from Cloud Connect for the isolated machine. Thetransfer API or transfer Cloud Connect web service is called with the information specified in thetable below:transfer Run-time API transfer Cloud Connect Web Service

o Current license state received from theisolated machine

o The REMOTE_DETACH actiono Detach intervalo Customer for whom licenses need to

be fetchedo User as NULL

o Current license state received from theisolated machine

o The RemoteDetach actiono Detach intervalo Customer for whom licenses need to

be fetchedo Vendor Id

7. In response of the transfer call, Cloud Connect sends the updated license state for theregistered isolated machine.

8. The updated license state is sent from connected machine to isolated machine. The end userdecides how to send the license state, for example, by using a USB dongle, over intranet, or byany other method.

License Deployment by Isolated Machine

9. The isolated machine applies the license update received from the connected machine. Thetransfer API is called with the updated license state and the APPLY_REMOTE_LICENSE action.

10. The isolated machine can use the deployed licenses.

It is not possible to transfer the usage data from isolated machines to Cloud Connect. So it isbetter to disable the usage collection feature while creating entitlements for isolatedmachines.

Detach Interval

The detach interval is the number of hours for which an entitlement can be detached for offline use onthe on-premisemachines. Themaximum detach interval is specified at entitlement level (in the DetachInterval field) and the actual duration to detach must be passed in the transfer API. The requestedduration must be less than themaximum detach interval configured while creating the entitlement.The end date of a feature as specified in the associated licensemodel also affects detach interval.

The following table describes how the actual duration of detach is determined:

Interval inTransfer API

Detach Intervalin Entitlement

LicenseEnd Date Actual License Availability

X hours No Limit No Limit X hours

X hours Y hours No Limit X or Y hours whichever is minimum

X hours Y hours Z hours X or Y or Z hours whichever is minimum

Interval inTransfer API

Detach Intervalin Entitlement

LicenseEnd Date Actual License Availability

-1 X hours No Limit X hours

-1 X hours Y hours X or Y hours whichever is minimum

-1 No Limit Y hours Y hours

-1 No Limit No Limit License with indefinite duration

As shown in the last row of the above table, you can generate licenses for an indefinite duration foron-premisemachines, by ensuring the following:

n Interval provided while calling the transfer API is -1.

n Detach Interval set in entitlement is No Limit.

n License end date is No Limit.

Terminal Server Support

In Entitlement Level mode, the 'Per Login' concurrency type does not require terminal server support.

If terminal server support is enabled, then you cannot detach licenses.

1.3.4. On-premise Feature Level Licensing

The feature level on-premise licensing solution is meant for the case where your protected applicationis installed as a client application on customer site. In this case, your on-premise application isprimarily a user application having multiple instances running on end user machines. Each of thesemachines could be accessed by multiple end users of a customer.

An end user needs access rights or licenses to use features of the protected application. The licensesare served from Cloud specifically for the end user who is requesting features from an instance of theprotected application.

There are two modes in which licenses are granted to a user:



n Connected: The Connected mode is used in scenarios where the protected application isalways connected to Cloud Connect with very small offline time. If the user is requestingfeature for the first time, the license request is served from Cloud. The license obtained fromCloud is stored in a local cache on themachine from where the user placed the request. Thesubsequent calls for that license by the same user are served locally from the cache. Since thelicenses are served from cache, the applications can survive short networkdisconnects.However, licenses do not persist across application restart or system reboot.

For concurrent licensemodels, the license request by an end user is processed directlyfrom Cloud.

n Detached: The Detached mode allows an end user to detach a license from Cloud Connect fora comparatively larger amount of time. This enables the end users to use their applicationoffline for a given duration. For example, when an employee needs to travel on business andwants to take along the protected application.

Themaximum duration for which the on-premise application can remain disconnected fromCloud Connect is configured by ISV. In this mode, the licenses persist across applicationrestart and system reboot.

Both modes support subscription, post-paid, and concurrent licensemodels.

Main Features

The key aspects of feature level on-premise licensing solution are:

n Application Installed on End User’s Machine: Your on-premise application is a user/clientapplication rather than a web server application. The application obtains rights directly fromcloud by implementing Run-time API calls.

n User Authentication (Optional): You can integrate your authentication system with SentinelCloud for authenticating a user before delivering licenses to a user’s machine. The identity ofthe user will be established after successful authentication and the required licenses will bedelivered to themachine from which user authenticates. For more information, see UserAuthentication (Optional).

Please contact SafeNet if you want to integrate an authentication system with SentinelCloud.

n User Centric Licenses: The license is provided in context of a user. The protected applicationneeds to request a feature separately for each user who wants to use the feature.

n Concurrency Management: Concurrency is centrally controlled from the cloud. For details,see Concurrency Management.

n Support for Machine Registration: You can specify a list of registered on-premisemachines (ifrequired), only on which your application will be accessed by customer’s end users. Fordetails, seeMachine Registration and Verification (Optional).

n Persistent Usage Store: The usage data is stored in a persistent store (physical disk), where-from the data is synced with Cloud Connect at regular intervals. The persistent store ensuresrecovery of usage information in cases ofmachine reboot and network failure.

n On-premise Provisioning: The on-premise entitlements meant for client deployment are cre-ated in EMS with the Feature Level option selected. While creating such entitlements, the fol-lowing information is also specified:

o Detach Interval: Duration (in hours) for which features can be detached.

o Cache Interval: Duration (in minutes) for which licenses are stored in local cache by anon-premisemachine.

n Entitlement Type Support: Only enterprise unnamed entitlement types are supported.

n License Models Support: The on-premise feature level licensing supports the following licensemodels:

n Subscription

n Postpaid

n Concurrent with Per Identity Per Station counting type

n Interface Support: The on-premise feature level licensing is available for Java, .NET, and Cinterfaces.

User Authentication (Optional)

You can use on-premise feature level licensing with authentication enabled or disabled. Ifauthentication is enabled, a user is authenticated before delivering licenses to a user’s machine.

To facilitate user authentication, an authentication system should be integrated with Sentinel Cloud.The authentication system interacts with Cloud Connect to process an authentication requestreceived from Run-time. The authentication system accepts user credentials obtained from Run-time,authenticates the credentials, and returns corresponding identity, customer reference ID, and cookie.

Please note the following:

n As an ISV, you need to host and manage the authentication system.

n You need to define the interfaces for communication between Sentinel Cloud componentsand authentication system.

Machine Registration and Verification (Optional)

Before granting rights to a user, Cloud Connect may verify that themachine from where the user isrequesting rights is also registered. This verification is required only if the ISV has placed a machinerelated restriction. The ISVmay want to restrict the use of protected applications to a specific group ofmachines belonging to a customer. For this, themachines on which access needs to be allowed mustbe registered with Sentinel Cloud Connect.

The process ofmachine verification is optional, which implies:

n If none of themachines is registered with Cloud Connect, licenses can be served to anymachine which requests license.

n If machines are registered, licenses are served to the registered on-premisemachines only.



The process ofmachine registration includes obtaining the unique identification information of theon-premisemachine and registering it with Cloud Connect.

Steps in machine registration are:

1. (One-time step)Deciding the criteria that you want to use for machine identification andregistration.

2. Obtaining unique identification information (fingerprint, host name, or both) of a machine.

3. Calling EMS web service to register themachine identification information: You need to call theEMS web service Add FingerPrintwith themachine identification information (fingerprint, hostname, or both) to register themachine with the ISV. For details about web services available formachine registration, see EMS Web Services Guide.

It is your responsibility to integratemachine registration functionality in the protected application.See On-premise Entitlement Level Licensing to knowmore.

License Modes - Connected and Detached

A license is served in either Detached or Connectedmode in on-premise feature level licensing. Inthesemodes, a license get cached locally either automatically at the time of first fetching of thatlicense or explicitly when the application detaches a license from the cloud for local use for a specifiedinterval of time.

The licenses for Detached and Connected mode are stored in Detached store and Connected storerespectively.

The table below provides differences between Detached and Connected stores:

Criteria Detached License Store Connected License Store

Creation Created by the transfer API. The transferAPI stores and returns licenses fromdetached store.

Created by the first call to the login API.

Persistence The detached store and its featurespersist across application reboots. Oncethe detached store is created, it isavailable across system/applicationrestart, to all the applications on amachine.

The connected store and its features donot persist across application reboots. Thecached licenses get cleaned onreleaseLicenseClient call, system reboot, orapplication restart.

Availability The detached store is created per user ona machine. Each user of a customer hasone detached store, which is sharableacross applications for same user on amachine.

The connected store is created per user perapplication on a machine. Each user hasone connected store. The same user canhave different connected stores fordifferent applications on a machine.

LicenseRequest

Every feature needs to be explicitlyrequested to the detached store.

A single login request to a feature fetchesall the features (except concurrent) of aproduct to the connected store.

LicenseReturn

Features can be returned or detachedagain before they get expired.

Features cannot be returned.

Criteria Detached License Store Connected License Store

LicenseRefresh

Features in detached store are notrefreshed.

Features in connected store are refreshedperiodically.

LicenseTime Slice

Longer time slice as specified by acustomer. For information on how detachinterval is determined, refer to sectionDetach Interval.

Shorter time slice as configured bycustomer while creating entitlement, in thecache interval property.

ConcurrentLicenseModel

Licenses for concurrent features arecached. Themaximum detach time limit isspecified by ISV.

Licenses for concurrent features are notcached.

Notes:

n If an authentication system is in place, a valid cookie is must to get the feature in connectedand detached stores. Also, the cookie is required for every login call for features in connectedstore.

n For concurrent features, once detached, any number of login is possible till the feature getsexpired.

n A background process refreshes all the connected stores created during an applicationinstance. If the cookie is found invalid during the refresh process, the Run-time removes thecookie from its memory.

n The expired, disabled, and excluded features are not removed from connected store duringthe refresh process. However, the customer will be able to consume these features only tillthe license time slice.

Concurrency Management

Concurrency is centrally managed from Cloud Connect for feature level on-premise licensing. Theconcurrent licensemodels provide the Per Station Per Identity concurrency type, which counts eachuser-machine pair as one session. All the login requests by the same user from the samemachine arecounted as one session, and consume only one concurrency limit.

Concurrency is counted as follows:

n A user accessing the single instance application on the samemachine is counted as ONEcount.

n A user accessing themultiple instances of an application on the samemachine is counted asONE count.

n The same user accessing themultiple instances of the application on multiple machines iscounted as N usage, where N is the number ofmachines.

n If a user accesses an application from a terminal server, it is counted as ONE count.

When a concurrent license is detached by a user on a machine, the license gets reserved for the user.The license is cached locally for the duration of the detached interval. During this duration, theavailable concurrency count remains decremented in the cloud, whether the license is actually in useor not.



Terminal Server Support

The on-premise deployments with Feature Level caching mode provides the ability to detect accessfrom a remote client (machine running Remote Desktop Connection). If an application is running on aterminal server and is being accessed on remote clients, you can still be able to effectively enforce theconcurrency based on Per Identity Per Station counting type.

You can choose to enable or disable terminal server support by contacting SafeNet Support. Bydefault, terminal server support is enabled.

The following table explains the licensing behavior with terminal server support enabled or disabled.

Terminal Server Support Enabled Terminal Server Support Disabled

Login from every terminal client is counted as adiscrete license count.

Login from all terminal clients is counted as a singlelicense count.

Terminal client cannot call transfer with detachand cancel detach actions.

Terminal client can call transfer with detach andcancel detach actions.

Terminal client cannot consume license fromdetached license store.Terminal client can consume license only fromConnected license store or directly throughCloud Connect (in case of concurrent licenseonly).

Terminal client can consume licenses fromdetached license store.

Terminal server support is available in On-premise Feature Level Licensing Connected Mode.

1.3.5. Comparing On-premise Feature Caching Modes

Following are key differences between feature caching modes available for on-premise deployment:

Entitlement Level Feature Level

Entitlement needs to be pulled to a localmachine before it can be consumed.

Entitlement can be directly consumed from CloudConnect.

License enforcement happens locally. License enforcement happens in Cloud.

Concurrency is managed locally and provides a Concurrency is managed centrally from Cloud


local view (of licenses available locally). Connect and provides a global view

By default, license that have been detached on amachine can be consumed offline (for the detachinterval).Note: The entire entitlement and itsproducts/features are available.

To work offline, you need to explicitly detachlicenses.Note: The required features need to be detachedexplicitly.

Rights are obtained by associating a particularentitlement with a machine.

Rights are obtained by explicit API calls from thelicensed application to the integrated Run-time.

An entitlement can be shared by more than onemachine. The number ofmachines that canshare the same entitlement is configurable byISV.

There is no association of an entitlement with alocal machine. Individual features occurring inone or more entitlements can be separatelyrequested by one or more Run-time instances.

Machine registration associates one or moremachines with an entitlement. Machineidentification information(fingerprint, hostname, or both) are added to an entitlement tocontrol who can pull the entitlement.Machine registration is a mandatory step. Theentitlement is served to the registered on-premisemachines only.

Machine registration associates a machine with acustomer.It is an optional step. If none of themachines isregistered with Cloud Connect, licenses can beserved to any machine which requests license.Ifmachines are registered, licenses are served tothe registered on-premisemachines only.

Time limited licenses for all features in theentitlement are automatically fetched from thecloud and made available locally. No automaticrenewals after the detached period expires.

Two modes of obtaining licenses:

n Connected : License for a feature fetchedon demand when requested for the firsttime. The license is then subsequentlycached locally and refreshed periodically.

n Detached: Application can explicitlyrequest a feature to bemade availablelocally for a particular amount of the time.No automatic renewals after the detachedperiod expires.

Supports machines on isolated networks (whichare never connected to the Internet).

Does not support isolated networks.

1.4. Comparing Cloud Run-time, On-premise Run-time, andCloud Connect Web ServicesThe following table explains key differences between Cloud and On-premise offerings.

Cloud Run-time Cloud Connect Web Services On-premise Run-time

Designed primarily for a hostedsolution under the control of a

Designed for a hosted solutionunder the vendor control. Can be

Designed for hosting atcustomer’s premises (that is,

1.4. Comparing Cloud Run-time, On-premise Run-time, and Cloud Connect Web Services 23



vendor. used on platforms or forlanguages for which there is noCloud Run-time available.

in a hostile environment).

You need to protect(envelope) theapplication toprevent reverseengineering attacksand tampering withlicense calls.

Non-globally concurrent licenses(subscription, post-paid) arecached in-memory when they arefetched, and subsequently servedfrom local cache until expiry.Globally concurrent licenses(concurrent, pre-paid) are alwaysfetched synchronously.

Licenses are always fetchedsynchronously from the cloud,irrespective of the licensemodel.

The number of networkcalls to Cloud Connect forthe non-globallyconcurrent licenses islikely to be higher thanthat in the case of theCloud Run-time.

Time-limited licenses for allthe features of a designatedentitlement are cachedpersistently on localmachine.Licenses are always servedfrom the local cache.For on-premise feature levellicensing connected mode,the licenses are updatedperiodically, independent ofthe actual license requests.

The usage information is storedtemporarily in memory at theclient end and pushed back toCloud Connect periodically.

No usage stored at the client end.Usage information is recorded atCloud Connect only when thesynchronous login and logoutcalls are received by the backend.

Usage is temporarily storedin a persistent manner at theclient end before it is pushedto the Cloud Connect duringthe periodic State Sync call(provided a connection isavailable).

Available for Java, .NET, and C Can be used with any languagethat supports HTTPS with server-side authentication

Available for Java, .NET, andC

Available on Windows and Linux Can be used on any platform thatsupports HTTPS with server-sideauthentication

Available on Windows andLinux

Supports both named andunnamed entitlements

Supports both named andunnamed entitlements

Currently supports only theunnamed entitlements

Supports all licensemodels(subscription, post-paid,concurrent, and pre-paid)

Supports all licensemodels(subscription, post-paid,concurrent, and pre-paid)

Support subscription, post-paid and concurrent licensemodels. Support for pre-paidlicensemodel is not available

Concurrency is counted Per Loginor Per Identity

Concurrency is counted Per Loginor Per Identity

Concurrency is counted asfollowing:

n Per Login for on-premise entitlement


level licensingn Per Identity Per

Station for on-premisefeature level licensing

1.5. Secure Communication Using Certificates and MessageSigning

1.5.1. SSL Based Communication

Critical communication takes place between the various components of Sentinel Cloud Services. Toensure safety, the communication between the following happens over SSL (https):

n Run-time and Directory Services

n Run-time and Cloud Connect

The SSL based authentication is enabled in order to avoid fallacious communication between SentinelCloud Run-time, Cloud Connect, and Cloud Directory Services. If a component is authenticated, asession will be established, otherwise the communication will be denied. This secure communicationchannel:

n Prevents acknowledgment of any external data on each end.

n Prevents tampering of data in transit.

n Maintains the integrity of the usage data.

The following authentication processes are used during SSL to establish identity of server and clientcomponents:

n Message Signing is used for client authentication.

n Certificates issued by a well-known Public CA are used for server authentication.

1.5. Secure Communication Using Certificates and Message Signing 25


1.5.2. Server Authentication Using Public CA Certificates

A server component authenticates itself to a client by presenting the certificate issued by a publicCertificate Authority(CA).

The server-side components (Cloud Connect, EMS, and Directory Services) contain the followingcertificate and keys:

n Public CA Certificate: The certificate signed by a well-known public CA.

n Private and Public Key: The key pair in PKCS12 format for mutual authentication.

1.5.3. Client Authentication Using Message Signing

The process ofmessage signing is used to authenticate client requests. The entities required formessage signing are: VendorID, SecretKey, and SecretKeyID.

1. The client applies HMAC-SHA1 algorithm on Secret Key to create a signature.

2. Themessage signed with signature is sent to server along with Secret Key ID.

3. The server retrieves the Secret Key ID from received message, and derives the correspondingSecret Key.

4. The server computes the signature using the samemechanism as used by client.

5. If the received signature and computed signaturematch, the client is authenticated and therequest is served. Otherwise the client request is denied.

See Also:

n Chapter 6: Integrating Cloud Run-time APIs

1.6. Compatibility and Support

Run-time Compatibility

n Cloud Run-time 3.5 will only work with Cloud Connect 3.5 and later versions.

n The compilation of existing applications will break because of the changes inacquireLicenseClient signature. If you are upgrading from v.3.4 to v.3.5, modify application toaccommodate signature change to ensure that your applications continue to compileproperly.

Cloud Connect Compatibility

n Cloud Connect 3.5 is backward compatible with earlier Cloud Run-time versions.

Platform Support

Refer to the Release Notes for information about platforms supported by Run-time.

Chapter 2:Cloud Run-time APIs

Sentinel Cloud Run-time provides the following APIs:

API Description

acquireLicenseClient Obtains an instance of the Cloud Run-time.

login Authorizes a user by requesting a license from the Cloud Connect.

logout Releases the license acquired by the user.

getInfo Retrieves information about entitlements and features for a given user.Also retrieves fingerprint and current license state of on-premisemachines.

releaseLicenseClient Releases the instance of the Cloud Run-time.

Additional APIs for Cloud Licensing

refreshSession Refreshes a concurrent session.

Additional APIs for On-premise Licensing

getIdentity Authenticates a user.

This API is available only for on-premise feature level licensing,implemented with authentication. To use this API, an authenticationsystem should be integrated with Sentinel Cloud. Please contactSafeNet for integration-related details.

transfer Detaches licenses, returns licenses, applies license update, and syncs usagewith Cloud Connect.

Further sections describe Cloud Run-time APIs and their processing in detail.

2.1. API Usage Guidelines 28

2.2. acquireLicenseClient 29

2.3. getIdentity 35

2.4. transfer 42

2.5. getInfo 52

2.6. login 62

2.7. refreshSession 72

2.8. logout 76

2.9. releaseLicenseClient 80

2

28 Chapter 2: Cloud Run-time APIs

2.1. API Usage GuidelinesWe recommend reviewing the information given in this section before using Cloud Run-time APIs.

About Calling Sequence

Given below is a typical sequence in which your application can call Run-time APIs, for Cloud and On-premise licensing:

Cloud Licensing On-premise Licensing


1. acquireLicenseClient2. getInfo3. login4. refreshSession5. logout6. releaseLicenseClient

1. acquireLicenseClient2. transfer3. getInfo4. login5. logout6. releaseLicenseClient

In the case of isolated networks,separate API calls aremadefrom isolated and connectedmachines. For details, seeWorkflow for IsolatedMachines.

1. acquireLicenseClient2. getIdentity (applicable

only if authentication hasbeen implemented)

3. getInfo (can also be calledafter transfer)

4. transfer (optional)5. login6. logout7. releaseLicenseClient

Notes:

n To use the getIdentity API, an authentication system should be integrated with SentinelCloud. Please contact SafeNet for integration-related details.

n The getInfo API can be called between the acquireLicenseClient and releaseLicenseClient APIs.

n For on-premise feature level licensing, the transfer API call is optional. For on-premiseentitlement level licensing, the transfer API call is mandatory before calling login and getInfoAPIs.

Handling Stateless APIs

The Sentinel Cloud Run-time APIs are stateless. The communication between individual nodes is notrequired. The login to a session can be performed from one node and logout from another. Eachsuccessful login request returns a session handle. This session handle needs to be specified in thecorresponding logout call to enable Cloud Connect map the specific login and logout events to acomplete session (with start time, end time, user ID, enterprise ID, feature ID, etc.).

The on-premise licensing is not stateless.

About Character Encoding

All APIs support internationalization.

n For Java and .NET APIs, the input should be in UTF-16 format. The output will be in UTF-16.

n For C APIs, the input should be in UTF-8 format. Output will be in UTF-8.

2.2. acquireLicenseClientInitializes the Cloud Run-time.

2.2.1. Description

The API performs the following functions:

n Initializes the Cloud Run-time and its following internal components:

ComponentInterface

On-premiseJava .NET C

Communication moduleEstablishes communication with the CloudConnect.

SchedulerPerforms periodic job processing in order tosend usage logs to the Cloud Connect.

SerializerSerializes request objects to be sent to theCloud Connect.

CacheStores recently used licenses.

Not Applicable

n Interacts with the Cloud Directory Services to register the Cloud Run-time and request details,like which Cloud Connect nodes will be serving the Cloud Run-time.

n Interacts with the Cloud Connect for request processing.

2.2.2. Setting Run-time Configuration Properties

The acquireLicenseClient API allows you to provide the InMemoryUsageCount configuration propertyto Run-time during initialization. You can set configuration properties in the configuration parameterof the acquireLicenseClient API. For details, see section Configuration.

These properties are additional to those defined in the Client Configuration File.

2.2.3. API Calling Sequence

The acquireLicenseClient API is called once during an application's life cycle for initializing the Run-timecomponents. The environment it sets up is constant for the life of the application and is the same for



every application, so multiple calls have the same effect as one call.

n This API is called before calling any other Cloud Run-time API.

n The acquireLicenseClient API obtains a Cloud Run-time instance, which is used forauthorizing a user.

n There is only one Cloud Run-time instance for an application node. So, the applicationdoes not need to save the instance.

2.2.4. acquireLicenseClient (Java)

Format

public static LicenseRuntime

acquireLicenseClient(

Configuration configuration,

AcquireClientOptionalParam optParam,

AcquireClientResponse response) throws LicenseException

Parameters

ParameterDataType

Description

configuration Class Object of the Configuration class , containing configuration properties to bepassed to Run-time.

optParam Class Object of the AcquireClientOptionalParam class , which is reserved for futureuse. You can pass null value for this release.

response Class Object of the AcquireClientResponse class , which is reserved for future use.You can pass null value for this release.

Returns

A singleton instance of LicenseRuntime object.

Exception Handling

Throws LicenseException with one of the following error codes:

n RT_ERR_NO_AUTH_SERVER

n RT_ERR_CRT_NOT_INITIALIZED

n RT_INTERNAL_ERR

n RT_ERR_INTERNAL_SYS

n RT_ERR_IN_COMMUNICATION

n RT_ERR_IN_CONF_FILE_LOAD

n RT_ERR_INVALID_SERVER_CONN_TIMEOUT

n RT_ERR_INVALID_SERVER_RETRY_COUNT

n RT_ERR_INVALID_YPS_ADDRESS

n RT_ERR_INVALID_REG_NODE_URL

n RT_ERR_INVALID_DEREG_NODE_URL

n RT_ERR_INVALID_SUPP_NODE_URL

n RT_ERR_INVALID_HEART_BEAT_URL

n RT_ERR_INVALID_JOB_INTERVAL

n RT_ERR_INVALID_CLIENT_ALIAS

n RT_ERR_INVALID_NODE_DESCRIPTION

n RT_ERR_INVALID_PROXY_ADDRESS

n RT_ERR_INVALID_PROXY_PORT

n RT_ERR_INVALID_DEPLOYMENT_TYPE

n RT_ERR_INVALID_PERIODIC_REFRESH_TIME

n RT_ERR_INVALID_GCS_INTERVEL

n RT_ERR_INVALID_VENDERINFO_LEN

n RT_ERR_INVALID_WORST_TIME_MULTIPLIER

n RT_ERR_INVALID_USAGE_LOG_PATH

n RT_ERR_INVALID_AUTHENTICATION

n RT_ERR_INVALID_VENDOR_ID

n RT_ERR_INVALID_SECRET_KEY

n RT_ERR_INVALID_SECRET_KEY_ID

n RT_ERR_INVALID_CA_BUNDLE

n RT_ERR_INVALID_PARAMETER

For description of the error codes, see the topic Error Codes. For identifying the reason of error, callthe getErrorCode API of the LicenseException class.

See Also:

Sample Code - acquireLicenseClient (Java)

2.2.5. acquireLicenseClient (.NET)

Format

public static LicenseRuntime

acquireLicenseClient(

Configuration configuration,

AcquireClientOptionalParam optParam,



AcquireClientResponse response) throws LicenseException

Parameters

ParameterDataType

Description

configuration Class Object of the Configuration class , containing configuration properties to bepassed to Run-time.

optParam Class Object of the AcquireClientOptionalParam class , which is reserved for futureuse. You can pass null value for this release.

response Class Object of the AcquireClientResponse class , which is reserved for future use.You can pass null value for this release.

Returns

A singleton instance of LicenseRuntime object.

Exception Handling




n RT_INTERNAL_ERR















n RT_ERR_INVALID_SERVER_READ_WRITE_TIMEOUT

n RT_ERR_INVALID_MAX_QUEUE_SIZE

n RT_ERR_INVALID_JOB_BATCH_SIZE

n RT_ERR_INVALID_CLIENT_LICENSE_CACHE

n RT_ERR_INVALID_CERT_EXT_KEY



n RT_ERR_INVALID_VENDOR_ID

n RT_ERR_INVALID_SECRET_KEY

n RT_ERR_INVALID_SECRET_KEY_ID



For description of the error codes, see the topic Error Codes. For identifying the reason of error,access the errorCode properties of the LicenseException class.

See Also:

Sample Code - acquireLicenseClient (.NET)

2.2.6. scr_acquireLicenseClient (C)

Format

int scr_acquireLicenseClient

(

scr_Configuration_t * configuration,

scr_

AcquireClientOptionalParam_t

* optParam,

scr_AcquireClientResponse_t ** response)

Parameters

Parameter Data Type Description

configuration scr_Configuration_t* Structure of the type scr_Configuration_t (C),containing configuration properties to be passedto Run-time.

optParam scr_AcquireClientOptionalParam_t*

Structure of the type scr_AcquireClientOptionalParam_t (C), which isreserved for future use. You can pass NULL valuefor this release.

response scr_AcquireClientResponse_t**

Structure of the type scr_AcquireClientResponse_t(C), which is reserved for future use. You can passNULL value for this release.



Returns

The status code RT_SUCCESS is returned if successful. Otherwise, it will return one of the followingerror codes:



n RT_ERR_IN_CERT_LOAD

n RT_ERR_IN_LOCKING

n RT_INTERNAL_ERR


n RT_ERR_NO_RESOURCE_AVAILABLE

n RT_ERR_IN_REGISTRATION


n RT_ERR_COULDNT_RESOLVE_PROXY

n RT_ERR_COULDNT_RESOLVE_HOST

n RT_ERR_OPERATION_TIMEDOUT

n RT_ERR_SSL_CONNECT_ERROR

n RT_ERR_PEER_FAILED_VERIFICATION

n RT_ERR_SSL_CERTPROBLEM

n RT_ERR_SSL_CACERT_BADFILE

n RT_ERR_SSL_CACERT











n RT_ERR_INVALID_NODE_DESCRIPTION

n RT_ERR_INVALID_PROXY_ADDRESS

n RT_ERR_INVALID_PROXY_PORT

n RT_ERR_INVALID_REGISTRATION_WS_URL

n RT_ERR_INVALID_DEPLOYMENT_TYPE

n RT_ERR_INVALID_PERIODIC_REFRESH_TIME


n RT_ERR_INVALID_VENDERINFO_LEN





n RT_ERR_CLR_OLD_LOCK


For description of the error codes, see the topic Error Codes.

See Also:

Sample Code - scr_acquireLicenseClient (C)

2.3. getIdentityAuthenticates a user of a customer.

n This API is available only for on-premise feature level licensing.

n To use this API, you need to integrate an authentication system with Sentinel Cloud. Ifthe authentication system is not available, you can implement on-premise featurelevel licensing, but without using authentication. For information on how to integratean authentication system, please contact SafeNet.

2.3.1. Description

The getIdentity API returns cookie ID, identity, and customer reference ID to your application, whichyou can use as parameters in login and transfer API calls.

The cookie is a token used for authorizing license generation calls (login and transfer). This API is alsoused to retrieve the authPayLoad string, which acts as a placeholder for storing additional userinformation in the authentication system.

2.3.2. Workflow

The following diagram illustrates how getIdentity API works.

2.3. getIdentity 35


1. The ISV application calls the getIdentity API with user name, data blob, and action.

2. Run-time checks the action parameter and decides if the call should be served from local cacheor transferred to Cloud Connect. The action parameter can have one of the following values:

n Cloud: License is served from Cloud Connect, by using the following process:

a. The call is routed to Cloud Connect, provided connection with Cloud Connect isavailable.

b. Cloud Connect calls external authentication system (set by ISV) with the authen-tication information – user name and blob.

c. The authentication system verifies user credentials; and on successful authen-tication the authentication system returns the corresponding identity, cus-tomer reference ID, and authPayLoad string to Cloud Connect. TheauthPayLoad string acts as a placeholder for storing additional user informationin the authentication system.

d. Cloud Connect creates a cookie, stores this cookie along with the returned userinformation in Cloud Connect, and returns the same to Run-time.

e. The identity, customer reference ID, cookie, and authPayLoad for a user arereturned to Run-time, and all the values except authPayLoad are stored in alocal cache.

The cookie remains valid for a specific duration as defined by the ISV.

n Local: Run-time checks if the specified user name exists in the local cache. If so, itreturns the corresponding cached identity and customer reference ID.

To retrieve identity and customer reference ID from local store, the getIdentity musthave been called at least once with action as cloud.

3. The returned values (identity, customer reference ID, and cookie) are used in login and transferAPI calls.


n The getIdentity API should be called after acquireLicenseClient.

n The getIdentity API should be called before login or transfer.

2.3.4. getIdentity (Java)

Format

public void getIdentity(

String userName,

String action,

String blob,

GetIdentityOptionalParam optParam,

GetIdentityResponse response) throws LicenseException

Parameters

ParameterDataType

Description

userName String Name of the user to be authenticated.

action String Specifies if the user should be authenticated from cloud or from local cache. Itcan have one of the following values:

n Cloud: It is used to authenticate a new user. In this case, yourapplication requests cookie, customer reference ID, and identity fromCloud Connect.

n Local: It is used to retrieve customer reference ID and identity stored inlocal cache.

blob String It represents data that the authentication system integrated with Run-timeworks with, which can be a password, token, handle, or any other characterstring.Sentinel Cloud does not interpret the value in this field.

Your application is able to retrieve cookie, customer reference ID, andidentity from Cloud Connect only if both user name and its mappedblob value are correct.

optParam Class Object of the GetIdentityOptionalParam class, which is reserved for future use.

response Class Object of the GetIdentityResponse class, containing response of thegetIdentity API.

Returns

None

2.3. getIdentity 37


Exception Handling





n RT_ERR_IN_LOCKING

n RT_INTERNAL_ERR



n RT_ERR_GETTING_IDENTITY_INFO

n RT_ERR_AUTHENTICATION_IS_OFF

n RT_ERR_OPERATION_NOT_SUPPORTED







n RT_ERR_SSL_CACERT

n RT_ERR_COULDNT_DETECT_PROXY


n RT_ERR_UNKNOWN_ERROR

n RT_ERR_INTERNAL_SCC

n RT_ERR_IN_USER_AUTHENTICATION

n RT_ERR_AUTH_PAY_LOAD_SIZE_EXCEEDS


See Also:

Sample Code - getIdentity (Java)

2.3.5. getIdentity (.NET)

Format

public void getIdentity(

String userName,

String action,

String blob,

GetIdentityOptionalParam optParam,

GetIdentityResponse response)

Parameters

ParameterDataType

Description

userName String Name of the user to be authenticated.

action String Specifies if the user should be authenticated from cloud or from local cache.It can have one of the following values:

n Cloud: It is used to authenticate a new user. In this case, yourapplication requests cookie, customer reference ID, and identity fromCloud Connect.

n Local: It is used to retrieve customer reference ID and identity storedin local cache.

blob String It represents data that the authentication system integrated with Run-timeworks with, which can be a password, token, handle, or any other characterstring.Sentinel Cloud does not interpret the value in this field.

Your application is able to retrieve cookie, customer reference ID,and identity from Cloud Connect only if both user name and itsmapped blob value are correct.

optParam Class Object of the GetIdentityOptionalParam class, which is reserved for futureuse.

response Class Object of the GetIdentityResponse class, containing response of thegetIdentity API.

Returns

None

Exception Handling




2.3. getIdentity 39



n RT_ERR_IN_LOCKING

n RT_INTERNAL_ERR












n RT_ERR_SSL_CACERT







For description of the error codes, see the topic Error Codes. For identifying the reason of error, callthe errorCode properties of the LicenseException class.

See Also:

Sample Code - getIdentity (.NET)

2.3.6. scr_getIdentity(C)

Format

int scr_getIdentity(

char * userName,

char * action,

char * blob,

scr_

GetIdentityOptionalParam_t

* optParam,

scr_GetIdentityResponse_t ** response)

Parameters


userName char* Name of the user to be authenticated.

Action char* Specifies if the user should be authenticated fromcloud or from local cache. It can have one of thefollowing values:

n Cloud: It is used to authenticate a new user. Inthis case, your application requests cookie,customer reference ID, and identity fromCloud Connect.

n Local: It is used to retrieve customer referenceID and identity stored in local cache.

Blob char* It represents data that the authentication systemintegrated with Run-timeworks with, which can be apassword, token, handle, or any other characterstring.Sentinel Cloud does not interpret the value in thisfield.

Your application is able to retrieve cookie,customer reference ID, and identity fromCloud Connect only if both user name and itsmapped blob value are correct.

optParam scr_GetIdentityOptionalParam_t*

Structure of the type scr_GetIdentityOptionalParam_t (C), which is reserved for future use. You can passNULL value for this release.

response scr_GetIdentityResponse_t**

Structure of the type scr_GetIdentityResponse_t (C)containing response of the scr_getIdentity API.

Returns







n RT_ERR_IN_LOCKING

n RT_INTERNAL_ERR


2.3. getIdentity 41










n RT_ERR_SSL_CACERT








See Also:

Sample Code - getIdentity (C)

2.4. transferThis API is available only for on-premise licensing, and is used to perform the following functions:

n Detaches a license on a host machine. A defined number of features or all features within anentitlement are detached.

n Cancels detached licenses on a host machine and returns licenses to Cloud Connect.Canceling a license also releases the host machine (station) in case of entitlement level on-premise licensing.

n Transfers usage data synchronously from Run-time to Cloud Connect.

n Detaches a remote license for use on an isolated machine (which is never connected to theInternet). All features within an entitlement are detached.

n Applies the remote license on an isolated machine.

Notes

n The transfer API is available only for on-premise licensing.

n There is no limitation on the number of times a feature can be detached or returned.

n Cloud Connect always verifies themachine fingerprint from database (if present)before detaching or canceling a license.

n The ability to detach and apply license on isolated machines is supported only by on-premise entitlement level feature caching mode.

The behavior of the transfer API varies depending on the on-premise feature caching mode, asexplained in the table below:


Fetches all features of an entitlement registeredagainst an on-premisemachine.

Fetches only the requested features, as given infeature list.

Returns all the detached licenses on cancellation. Returns only the features specified in the featurelist.

There is restriction on themaximum number ofmachines that can detach a license, as defined bythe station count field in EMS. Canceling a licensealso releases themachine, thereby decreasingthe station count by one.

There is no such restriction.

The user is specified as NULL. The feature list isignored, if specified.

It is mandatory to specify a user and a featurelist.

Once the transfer API has been called on a machine for an on-premise feature leveldeployment, it cannot be called for entitlement level deployment; and vice versa. Pleasecontact SafeNet Support if you want to change the type of on-premise deployment for amachine.


n The transfer API call is optional for on-premise feature-level licensing. You need to call thetransfer API if you want to detach licenses and use them for long offline periods.

n In the case of on-premise entitlement level licensing, the transfer API call is mandatory beforecalling the login API.

n The transfer API must be called between acquireLicenseClient and releaseLicenseClient.

2.4.2. transfer (Java)

Format

public void transfer(

String user,

2.4. transfer 43


String customer,

Action action,

SaaSFeatureNode[] featureNodes,

TransferOptionalParam optParam,

TransferResponse response) throws LicenseException

Parameters


user String Identifies the user. Required for both enterprise (named andunnamed) and retail users.You need to keep this parameter as NULL if you want to call transferAPI for on-premise entitlement level licenses served in detachedmode.

customer String The enterprise customer to whom the user belongs.It is a uniquereference ID of the customer as provided in EMS.

action Enumerator Enumerated data type that specifies the action to be performed bythe transfer API.Possible values are:

n DETACH(1): Detaches the license. In this case, you mustspecify a detach interval in the optParam parameter.

n CANCEL_DETACH(2): Returns the license to Cloud Connect. Italso releases the station in case of entitlement level licensing.

n SYNC_USAGE(4): Syncs all usage logs stored on a machine toCloud Connect. With this value, the transfer API call acts as ablocking call, as no other API can execute in the same threaduntil all usage is pushed to Cloud Connect.

This is optional. Use this option only when you do notwant to wait for periodic usage transfer and want tosend the usage instantly.

n REMOTE_DETACH(8): Detaches a license for an isolated on-premisemachine.

n APPLY_REMOTE_LICENSE(16): Applies the license update toan isolated on-premisemachine.

featureNodes Class Array of objects of the SaaSFeatureNode class. It contains list offeatures for which a transfer action needs to be performed.The feature list is ignored for on-premise entitlement level licensing.Authorization CriteriaFor on-premise, the authorization is done either on feature ID or onfeature name. You should provide only one of these featureidentifiers; otherwise an error will be returned.If a valid feature name is given, the feature ID should be zero or lessthan zero. If a valid feature ID is given, feature name should beNULL.


optParam Class Object of the TransferOptionalParam class containing optionalparameters to be passed with the transfer API.

response Class Object of the TransferResponse class.

Returns

None

Exception Handling





n RT_ERR_IN_LOCKING

n RT_INTERNAL_ERR



n RT_ERR_INVALID_IDENTITY

n RT_ERR_INVALID_COOKIE

n RT_ERR_IN_TRANSFER

n RT_ERR_RESYNC_ALREADY_IN_PROGRESS

n RT_ERR_INVALID_CUSTOMER

n RT_ERR_NO_EID_REGISTERED

n RT_ERR_MAX_STATION_COUNT_REACHED

n RT_ERR_NO_LICENSE_IN_DETACHED_STORE








n RT_ERR_SSL_CACERT


2.4. transfer 45



n RT_ERR_PUSH_USAGE_IN_SCC

n RT_ERR_LICENSE_NOT_ACTIVATED

n RT_ERR_LICENSE_IS_EXPIRED

n RT_ERR_LICENSE_IS_DISABLED

n RT_ERR_LICENSE_ERROR

n RT_ERR_LICENSE_IS_REVOKED

n RT_ERR_MAX_CONCU_LIMIT_REACHED

n RT_ERR_LICENSE_COUNT_EXAUSTED



n RT_ERR_LICENSE_DOES_NOT_EXISTS

n RT_ERR_INVALID_FEATURE_PARAMETER

n RT_ERR_CUSTOMER_PARAMETER

n RT_ERR_IDENTITY_PARAMETER

n RT_ERR_PARAMETER

n RT_ERR_NO_AUTH_SESSION

n RT_ERR_INVALID_FINGERPRINT

n RT_ERR_POLICY_DOES_NOT_ALLOW

n RT_ERR_INVALID_CUSTOM_CRITERIA

n RT_ERR_INVALID_LICENSE_STATE

n RT_ERR_DUPLICATE_LICENSE_STATE

For description of the error codes, see the topic Error Codes. For identifying the reason of error, youcan retrieve the error code value by calling the getErrorCode API of the LicenseException class.

See Also:

Sample Code - getInfo (Java)

2.4.3. transfer (.NET)

Format

public void transfer(

String user,

String customer,

Action action,

SaaSFeatureNode[] features,

TransferOptionalParam optParam,

TransferResponse response)

Parameters


user String Identifies the user. Required for both enterprise (named andunnamed) and retail users.You need to keep this parameter as NULL if you want to call thetransfer API for on-premise entitlement level licenses served indetached mode.

customer String The enterprise customer to whom the user belongs.It is a uniquereference ID of the customer as provided in EMS.

action Enumerator Enumerated data type that specifies the action to be performed bythe transfer API.Possible values are:

n DETACH(1): Detaches the license. In this case, you mustspecify a detach interval in the optParam parameter.

n CANCEL_DETACH(2): Returns the license to Cloud Connect. Italso releases the station in case of entitlement level licensing.

n SYNC_USAGE(4): Syncs all usage logs stored on a machine toCloud Connect. With this value, the transfer API call acts as ablocking call, as no other API can execute in the same threaduntil all usage is pushed to Cloud Connect.

This is optional. Use this option only when you do notwant to wait for periodic usage transfer and want tosend the usage instantly.

n REMOTE_DETACH(8): Detaches a license for an isolated on-premisemachine.

n APPLY_REMOTE_LICENSE(16): Applies the license update toan isolated on-premisemachine.

features Class Array of objects of the SaaSFeatureNode class. It contains featuresfor which a transfer action needs to be performed.The feature list is ignored for on-premise entitlement level licensing.Authorization CriteriaFor on-premise, the authorization is done either on feature ID or onfeature name. You should provide only one of these featureidentifiers; otherwise an error will be returned.If a valid feature name is given, the feature ID should be zero or lessthan zero. If a valid feature ID is given, feature name should be NULL.

optParam Class Object of the TransferOptionalParam class containing optionalparameters to be passed with the transfer API.

response Class Object of the TransferResponse class.

2.4. transfer 47


Returns

None

Exception Handling





n RT_ERR_IN_LOCKING

n RT_INTERNAL_ERR


















n RT_ERR_SSL_CACERT

















n RT_ERR_PARAMETER








See Also:

Sample Code - transfer (.NET)

2.4.4. scr_transfer (C)

Format

int scr_transfer(

char *user,

char *customer,

scr_Action_t action,

scr_Features_t features,

scr_TransferOptionalParam_t *optParam,

scr_TransferResponse_t **response)

2.4. transfer 49


Parameters


user char* Identifies the user. Required for both enterprise (namedand unnamed) and retail users.You need to keep this parameter as NULL if you want tocall transfer API for on-premise entitlement level licensesserved in detached mode.

customer char* The enterprise customer to whom the user belongs.It is aunique reference ID of the customer as provided in EMS.

action scr_Action_t An enumerator that specifies the type of transfer action.

features scr_Features_t Structure of the type scr_Features_t (C) containing list offeatures for which a transfer action needs to beperformed.The feature list is ignored for on-premise entitlement levellicensing.Authorization CriteriaFor on-premise, the authorization is done either onfeature ID or on feature name. You should provide onlyone of these feature identifiers; otherwise an error will bereturned.If a valid feature name is given, the feature ID should bezero or less than zero. If a valid feature ID is given, featurename should be NULL.

optParam scr_TransferOptionalParam_t*

Structure of the type scr_TransferOptionalParam_tcontaining optional parameters to be passed with the scr_transfer API.

response scr_TransferResponse_t** Structure of the type scr_TransferResponse_t (C).

Returns






n RT_ERR_IN_LOCKING

n RT_INTERNAL_ERR












n RT_ERR_SSL_CACERT















n RT_ERR_PARAMETER








2.4. transfer 51










See Also:

Sample Code - scr_transfer (C)

2.5. getInfoReturns information of entitlements, products, and features for a given user of the customer. It alsohelps check the license availability for a user.

2.5.1. Description

This API helps get authorization information of customer's entitlements. It fetches information basedupon the provided scope and returns results in the specified format.

2.5.2. Workflow

The following diagram illustrates how the getInfo API fetches information.

**If a feature exists in both Detached and Connected license stores, the feature information isreturned twice.

The above flow is not applicable for on-premise applications where getInfo is called with theMACHINE_ FINGERPRINT (8) and CURRENT_ LICENSE_STATE (16) format types.

Flow Details for Cloud Applications

The getInfo call is always served from Cloud.

Flow Details for On-premise Applications

The on-premise feature caching mode determines how the getInfo call is served, as explained below:

2.5. getInfo 53


Entitlement Level Feature Caching Mode

n If the transfer API has been called before:

o If peak capacity information is requested, getInfo is served from Cloud Connect. Thefeatures for which the Capacity Attribute has been defined in EMS are returned inresponse, from the registered entitlement.

o If peak capacity information is not requested, getInfo is served locally from theDetached license store.

n If the transfer API has not been called before, call is sent to Cloud Connect. If customer'smachine from which the request is received is registered to an entitlement (of type enti-tlement level) and if peak capacity information is requested, details of features having Capa-city Attribute defined in EMS are returned. Otherwise, an error is returned.

The above flow is not applicable for on-premise applications where getInfo is called with theMACHINE_ FINGERPRINT (8) and CURRENT_ LICENSE_STATE (16) format types.

Feature Level Feature Caching Mode

n The getInfo request is served from Cloud Connect, provided the connection between Run-time and Cloud Connect is available. Details of all features for the specific user of customersare returned.

However, if the peak capacity information has been requested, details of only those featuresare served for which Capacity Attribute has been defined in EMS.

n If Run-time is not able to establish connection with Cloud Connect, the getInfo request isserved from local license stores - Connected and Detached. If a feature exists in bothConnected and Detached licenses stores, the duplicate details are returned.

However, if peak capacity information has been requested, getInfo is not served locally.

For information about peak capacity, refer to section About Capacity.

2.5.3. When to use the getInfo API?

You can use the getInfo API in the following situations:

n Rendering application for a particular customer/user for better user experience

The getInfo API obtains a list of features that are available for use for a given user. You can usethis information to design an interface for the end user based on the features the user isauthorized to use. For example, you can display only those features to the user for which theuser is authorized, or you can enable the allowed features and disable the rest. This helps increating a better end user experience.

n Configuring Notifications

You can use getInfo to identify if the license is in grace state and can configure notifications for

the end user accordingly.

Notifications are not applicable for on-premise applications.

n Retrieving Prepaid Usage

You can call getInfo to show the usage available for prepaid licensemodels.

This is not applicable for on-premise applications.

n Retrieving Vendor Attribute Values

Vendor Attribute is a licensemodel attribute defined in EMS. It stores a vendor-defined valuefor a feature, for example, employee role or data download speed.

A software vendor can query vendor attribute values in an application by using the getInfo API.Based on getInfo results, the vendor can define application logic or can implement dynamicdecision making capabilities.

n A vendor attribute is not used by Cloud Connect in license enforcement.n EMS allows generating reports, 'Custom Vendor Attribute Report' and 'Feature

Usage Based on Vendor Attribute Report', based on vendor attribute. See EMSUser's Guide for details.

n Retrieving Peak Capacity Information

The getInfo API helps retrieve peak capacity data that you can use to implement checkswithin your application that notify end users when peak capacity of a feature reaches aspecified limit. For information about peak capacity, refer to section About Capacity.

You can use getInfo to retrieve the following information related to peak capacity of a feature:

n Capacity Attribute: A limit that is used for evaluating peak capacity data. It isspecified in EMS as a license attribute of postpaid licensemodels.

n Peak Capacity: The peak capacity of given feature(s) in the last N hours.The duration(in hours) for which you need to retrieve peak capacity information is specified as anoptional parameter of the getInfo API. Let us say, this duration is 5 hours. The getInfoAPI will retrieve the highest value of peak capacity in the last 5 hours of theaggregated data available in Cloud Connect.

The time interval, for which peak capacity is returned, is calculated with respect tothe last aggregation time, not with respect to the current time. The last aggregationtime refers to the last time the aggregation happened, that is when Cloud Connectprocessed the raw capacity records to compute peak capacity.

Time Interval = (last aggregation time – duration given in getInfo) to (last aggregationtime)

2.5. getInfo 55


Example

Let us say, the current time is 5-Oct-2013 23:55. The last aggregation time is 5-Oct-2013 13:30. If getInfo is called at 5-Oct-2013 23:58with a duration of 8 hours, it willfetch peak capacity from 5-Oct-2013 05:30 (last aggregation time – 8 hours) till 5-Oct-2013 13:30 (last aggregation time).

The getInfo API retrieves peak capacity information for those features for which:

n Capacity Attribute has been defined in EMS.n Licensemodel is Postpaid.

This functionality is available only for on-premise applications.

n Seamless Integration with EMS Web Services

The getInfo API returns the EID which can be used for EMS login and retrieving usage-relateddetails from EMS. For example, you can use the EID returned by getInfo in the Customer LoginBy EIDweb service to log in to EMS. By using other web services, you can get license attributedata and information about consumption of a particular entitlement, product, or feature.

The EMS URL cannot be auto-discovered and you need to pass it. For detailsabout other information that needs to be passed along with a web service,please refer to EMS Web Services Guide.

n Retrieving Machine Fingerprint and Current License State

You can call getInfo to retrieve the following information about an on-premisemachine:

n Fingerprint of an on-premisemachine

n Information of all the currently available licenses on a machine

n Retrieving Number of Active Sessions

The getInfo API also returns the number of active sessions for features with concurrentlicensemodels.

This information can be retrieved for cloud and on-premise feature level deployments, inconnected mode. For on-premise entitlement level deployment, 0 value is returned.

2.5.4. When NOT to use the getInfo API?

n Do not use getInfo if you want to retrieve usage of subscription, postpaid, and concurrentlicensemodels.

n Do not use getInfo to retrieve static data as required in case of subscription and postpaidlicenses. Examples of static data include details of an entitlement, product, feature, andlicense attributes (start date, end date, etc.).

In all the cases above, you should use EMS Web Services instead of getInfo.


n You must insert the getInfo API between the acquireLicenseClient and releaseLicenseClientAPI calls.

n You must call transfer before calling getInfo in the case of entitlement level licensing.

2.5.6. getInfo (Java)

Format

public void getInfo(

String user,

String customer,

Scope scope,

Format format,

GetInfoOptionalParam optionalParam,

GetInfoResponse response) throws LicenseException

Parameters

ParameterDataType

Description

customer String The unique reference ID of the customer as provided in EMS.

This parameter is optional for both retail and named users.However, it is must for supporting unnamed licenses in anenterprise.

user String Identifies the user. Required for both enterprise (named andunnamed) and retail users.

Make sure that user passed in the getInfo API and the oneused for configuring the license are exactly same.

scope Class Object of the Scope class containing query information for getInfo API.

format Class Object of the Format class specifying format for the returned data.

optionalParam Class Object of the GetInfoOptionalParam class containing optionalparameters to be passed with the getInfo API.

This parameter is applicable only for on-premise applications.

response Class Object of the GetInfoResponse class containing feature andentitlement list returned by the getInfo API.

Thememory for this object must be allocated by the caller.

Returns

None

2.5. getInfo 57


Exception Handling




n RT_ERR_IN_LOCKING

n RT_INTERNAL_ERR














n RT_ERR_SSL_CACERT




n RT_ERR_CAPACITY_ATTRIBUTE_NOT_FOUND



See Also:

Sample Code - getInfo (Java)

2.5.7. getInfo (.NET)

Format

public void getInfo(

String user,

String customer,

Scope scope,

Format format,

GetInfoOptionalParam optionalParam,

GetInfoResponse response)

Parameters


user String Identifies the user. Required for both enterprise (named andunnamed) and retail users.

Make sure that user passed in the getInfo API and the oneused for configuring the license are exactly same.


This parameter is optional for both retail and named users.However, it is must for supporting unnamed licenses in anenterprise.

scope Class Object of the Scope class containing query information for getInfoAPI.

format Class Object of the Format class specifying format for the returned data.

optionalParam Class Object of the GetInfoOptionalParam class containing optionalparameters to be passed with the getInfo API.

This parameter is applicable only for on-premise applications.

response Class Object of the GetInfoResponse class containing feature andentitlement list returned by the getInfo API.


Returns

None.

Exception Handling




2.5. getInfo 59


n RT_ERR_IN_LOCKING

n RT_INTERNAL_ERR














n RT_ERR_SSL_CACERT







For identifying the reason of error, retrieve the error code value as follows:

n Access the errorCode properties of the LicenseException class.

See Also:

Sample Code - getInfo (.NET)

2.5.8. scr_getInfo (C)

Format

int scr_getInfo(

char *user,

char *customer,

scr_Scope_t *scope,

scr_Format_t format,

scr_GetInfoOptionalParam_t * optParam,

scr_GetInfoResponse_t ** response)

Parameters


user char* Identifies the user. Required for both enterprise (namedand unnamed) and retail users.

Make sure that user passed in the scr_getInfoAPIand the one used for configuring the license areexactly same.

customer char* The unique reference ID of the customer as provided inEMS.

This parameter is optional for both retail andnamed users. However, it is must for supportingunnamed licenses in an enterprise.

scope scr_Scope_t* Structure of the type scr_Scope_t (C) containing queryinformation for the scr_getInfo API.

format scr_Format_t Structure of the type scr_Format_t (C) specifying format forthe returned data.

optParam scr_GetInfoOptionalParam_t

Structure of the type scr_GetInfoOptionalParam_t (C)containing optional parameters to be passed with the scr_getInfo API.

This parameter is applicable only for on-premiseapplications.

response scr_GetInfoResponse_t**

Structure of the type scr_GetInfoResponse_t (C) containingfeature and entitlement list returned by the scr_getInfoAPI.

Returns

The status code RT_SUCCESS is returned if successful. Otherwise, it will return the following errorcodes.



n RT_ERR_IN_LOCKING

n RT_INTERNAL_ERR




2.5. getInfo 61












n RT_ERR_SSL_CACERT






For description of the error codes, see the topic Error Codes (C).

See Also:

Sample Code - scr_getInfo (C)

2.6. loginObtains authorization for a feature requested by user, and returns a session handle to the licensedapplication.

2.6.1. Description

Only an authorized user can access features of the licensed application. The login API is used toauthorize the user's access to a feature. Once an authorization is obtained, the login API establishes asession between the licensed application and the Cloud Connect. Thereafter, this session is used forexchanging information.

n In Cloud deployment, the login API establishes a session between the licensed applicationand Cloud Connect. Licenses are served from Cloud Connect to Run-time.

n In On-premise deployment, the login API fetches features from local license store, instead ofCloud Connect. However for on-premise feature level connected mode, concurrent featuresare served from Cloud Connect.


The acquireLicenseClient API must be called at least once before calling the login API.

2.6.3. Additional Information for Cloud Deployment

Information Exchanged Between Cloud Run-time and Cloud Connect

To establish a session, the following information is exchanged between the Cloud Run-time and CloudConnect. The column 1 of the table below lists the information sent from the Cloud Run-time to CloudConnect and the column 2 of the table below lists the information sent from the Cloud Connect toCloud Run-time

Information Exchange

From Cloud Run-time to Cloud Connect From Cloud Connect to Cloud Run-time

n Session Identifier - Session IDcorresponding to the login request.

n Customer Identifier - Identifies thecustomer.

n user - Identifies the user.n Feature Identifier - Feature for which an

authorization is requested.n Client Node Identifier - Identifies the node

from where the request is received.n Vendor Identifier - Identifies the vendor

requesting user authorization.

n Authorization Identifier - Identifies thecustomer feature.

n Feature Identifier - Identifies thefeature for which authorization isrequested.

n Customer Identifier - Identifies thecustomer.

n FCG - Flag for Global Concurrency thatverifies if requested license is aglobally concurrent license or not.

n TTL - Time To Live. It is the time forwhich a license remains valid in cache.

After successfully receiving the response from the Cloud Connect, the Cloud Run-time prepares asession handle. The session handle contains information necessary for stateless functioning, such as:

n Session ID: Session ID allocated for this feature to the user.

n user: Identifies the user.

n Feature Info: Feature info contains a feature ID and a flag to identify the concurrent and non-concurrent licenses.

n Vendor ID: Identifies the vendor to whom the feature belongs.

2.6. login 63


Typical workflow of the login API for Cloud Deployment

Cloud Licensing

* License information is not cached for globally concurrent licenses (like pre-paid and concurrentlicenses). The logout request must be sent from Cloud Run-time to Cloud Connect for such licenses.

2.6.4. Additional Information for On-Premise Deployment

Workflow of the login API for On-premise Entitlement Level Licensing

On-premise Entitlement Level Licensing

Workflow of the login API for On-premise Feature Level Licensing

Here is how the login API works to support on-premise feature-level licensing:

1. Before a login call, Run-time calls the transfer API to fetch requested licenses, and storeslicenses locally.

2. For a login call, the Run-time first checks if the requested feature is among the detached fea-tures. The detached license is served locally from the cache.

3. If the requested feature is not among the detached features but available in the connectedstore, the license is served locally.

2.6. login 65


If authentication is enabled, the authentication cookie is always verified while servingconnected features. The authentication cookie is not checked while serving detachedfeatures.

4. If the license is not available locally, Run-timewill try to fetch the feature from Sentinel CloudConnect. Sentinel Cloud Connect delivers all the features of the product to which the requestedfeature belongs (in the connected store), after verification.

On-premise Feature Level Licensing

2.6.5. Consumption Order

To know the consumption order in the case ofmultiple entitlements, especially when same featureexists in multiple entitlements, please refer to the EMS User's Guide, Section "Duplicate Feature inMultiple Entitlements of a Customer - Deciding Consumption Order".

2.6.6. login (Java)

Format

public void login(

String user,

String customer,

SaaSFeatureNode featureNode,

LoginOptionalParam optParam,

LoginResponse response)throws LicenseException

Parameters


user String Identifies the user to be authorized. Required for both enterprise andretail users.

Make sure that user passed in this API and the one used forconfiguring the license are exactly same.


This parameter is optional for a retail user. However, it is mustfor supporting unnamed licenses in an enterprise.

FeatureNode Class Object of the SaaSFeatureNode class containing the feature for whichuser is requesting authorization.

optParam Class Object of the LoginOptionalParam class containing vendor-specificinformation.

response Class Object of the LoginResponse class that contains the data returned bythe login API.


Returns

Session Handle

Exception Handling

Throws LicenseException with one of the following:

2.6. login 67




n RT_ERR_IN_LICENSE_GET

n RT_INTERNAL_ERR









n RT_ERR_LICENSE_COUNT_EXHAUSTED







n RT_ERR_PARAMETER




n RT_ERR_LICENSE_EXPIRED_NO_CONNECTIVITY

n RT_ERR_NO_LICENSE_NO_CONNECTIVITY


See Also:

Sample Code - login (Java)

2.6.7. login (.NET)

Format

public String login(

String user,

String customer,

SaaSFeatureNode featureNode,

LoginOptionalParam optParam,

LoginResponse response)

Parameters


user String Identifies the user to be authorized. Required for both enterprise andretail users.

Make sure that user passed in this API and the one used forconfiguring the license are exactly same.


This parameter is optional for a retail user. However, it is mustfor supporting unnamed licenses in an enterprise.

featureNode Class Object of the SaaSFeatureNode class containing the feature for whichuser is requesting authorization.

optParam Class Object of the LoginOptionalParam class containing vendor-specificinformation.

response Class Object of the LoginResponse class that contains the data returned bythe login API.


Returns

Session Handle

Exception Handling

Throws LicenseException with one of the following:




n RT_INTERNAL_ERR






2.6. login 69












n RT_ERR_PARAMETER







For identifying the reason of error, access the errorCode properties of the LicenseException class.

See Also:

Sample Code - login (.NET)

2.6.8. scr_login (C)

Format

int scr_login(

char *user,

char *customer,

scr_FeatureNode_t *featureNode,

scr_LoginOptionalParam_t *optParam,

scr_LoginResponse_t **response)

Parameters


user char* Identifies the user to be authorized. Required for bothenterprise and retail users.

Make sure that user passed in this API and the


one used for configuring the license are exactlysame.

customer char* The unique reference ID of the customer as provided inEMS.

This parameter is optional for a retail user.However, it is must for supporting unnamedlicenses in an enterprise.

featureNode scr_FeatureNode_t* The structure of type scr_FeatureNode_t (C) containingthe feature for which user is requesting authorization.

optParam scr_LoginOptionalParam_t*

The structure of type scr_LoginOptionalParam_t (C)containing vendor-specific information.

response scr_LoginResponse_t**

The structure of type scr_LoginResponse_t (C)containing the data returned by the login API.

Returns

Session Handle

Error Handling

The status code RT_SUCCESS is returned if successful. Otherwise, it will return the following errorcodes:




n RT_ERR_IN_LOCKING

n RT_INTERNAL_ERR










2.6. login 71



n RT_ERR_SSL_CACERT














n RT_ERR_PARAMETER











See Also:

Sample Code - scr_login (C)

2.7. refreshSessionRefreshes the concurrent sessions periodically.

This API is available only for Cloud licensing.

2.7.1. Description

The refreshSession API performs the following functions:

n Avoids premature termination of concurrent sessions: This API refreshes the concurrent ses-sions periodically to keep the sessions alive for a longer period. Refreshing a session ensuresthat the background process does not kill the session after a specified time.

n Notifies an ISV application about terminated sessions: This API helps identify if a con-current session has been terminated or is still valid. For example, If a session is killed by a back-ground process or an ISV administrator, the API returns an error and ISV application does notallow the user to consume the feature further avoiding the license overuse.

n Cleans abandoned sessions: The background process checks for the presence of abandonedsessions and closes them. An abandoned session is one where the logout and refreshsessionAPI calls do not reach Sentinel Cloud Connect, for example, in the case of browser crash. Thisway the background process cleans abandoned sessions and makes the concurrency avail-able for consumption.

n Helps in usage tracking: The abandoned sessions are forced complete to ensure integrity ofusage data.

For more details about abandoned sessions, refer to topic Appendix F: Handling of AbandonedSessions.

2.7.2. Usage Notes

The licensed application should call this API periodically for refreshing sessions. For example, if theapplication allows onlinemovie watching, then the application brings buffer only for certain duration,then it fetches next buffer for next duration, and so on.The application calls the refreshSession APIand fetches the next buffer only if the session is still valid. If a user exits the browser without properlogout or due to any reason, the refreshSession API will return failure, and the background processwill auto complete the session according to the lastRefreshTimeStaleValue [Minutes] property andconcurrency will get free.

You need to set certain configurations for background process so that it can identify abandonedsessions and force them complete to free the concurrency.

The refreshSession API call:

n Is synchronous and is sent to Cloud Connect instantly.

n Is supported only for Cloud.

n Functions only for the Subscription Concurrent licensemodel.For other licensemodels, thisAPI returns success without updating the last refresh time.


This API should be called periodically between login and logout API.



2.7.4. refreshSession (Java)

Format

public void refreshSession(

String sessionHandle,

RefreshSessionOptionalParam optParam,

RefreshSessionResponse optParam) throws LicenseException

Parameters


sessionHandle String Session handle to be refreshed

optParam Class Object of the RefreshSessionOptionalParam class.This parameter isreserved for future use. It is optional and can be NULL.

response Class Object of the RefreshSessionResponse class containing the datareturned by the refreshSession API.


Returns

None

Exception Handling





n RT_ERR_SESSION_TERMINATED



See Also:

Sample Code - refreshSession (Java)

2.7.5. refreshSession (.Net)

Format

public void refreshSession(


RefreshSessionOptionalParam optParam,

RefreshSessionResponse response)

Parameters


sessionHandle String Session handle to be refreshed

optParam Class Object of the RefreshSessionOptionalParam class.This parameteris reserved for future use. It is optional and can be NULL.

response Class Object of the RefreshSessionResponse class containing the datareturned by the refreshSession API.


Returns

Session Handle

Exception Handling




n RT_INTERNAL_ERR




See Also:

Sample Code - refreshSession (.NET)

2.7.6. scr_refreshSession (C)

Format

int scr_refreshSession(

char *sessionHandle,

scr_RefreshSessionOptionalParam_t *optParam,

scr_RefreshSessionResponse_t **response)

Parameters


sessionHandle char* Session handle to be refreshed

optParam scr_RefreshSessionOptionalParam_t

Structure of the type scr_RefreshSessionOptionalParam_t (C) .This structureis reserved for future use. It is optional and can be




null.

response scr_RefreshSessionResponse_t Structure of the type scr_RefreshSessionResponse_t (C) containing the datareturned by the refreshSession API.

The caller is not required to allocatememory for response object, but the callermust freememory of response object.

Returns

Session Handle

Error Handling








See Also:

Sample Code - scr_refreshSession(C)

2.8. logoutReleases the user authorization.

Please note the following points for on-premise feature level licensing:

n After feature logout, a feature is released from the store from which it was served.

n The logout API call does not require cookie even if authentication is enabled.

n This logout API returns success even if the feature time slice has expired.

2.8.1. Description

Call this API when the user has finished using the feature.

The licensed application must manage the session handle received from the login API for each user.


The Run-time APIs are stateless in the case of Cloud licensing, so there is no need to free any resourcesusing the logout API. However, it is important to call this API, in a match with the login API, to log thelicense usage.

Special Cases

n If the licensed application exits without calling the logout API (such as in the case ofbrowser crash), the actual session logout timewill not be updated in the usage logs. Itis the software publisher's decision to account for such incomplete sessions. A fixedsession period could be assumed for such cases (for billing purposes). This periodneeds to be set on the Cloud Connect side. Contact SafeNet Technical Support forassistance.

n In the case of concurrent licenses, if the logout API is called while the Cloud Connect isdown, the license will be released automatically after a pre-defined period. The defaultvalue is 24 hours and can be configured by SafeNet. For count-based licenses, onecount will be consumed and currently this is not configurable by the publisher.

2.8.3. logout (Java)

Releases the authorization of a user.

Format

public void logout (


LogoutOptionalParam optParam,

LogoutResponse response) throws LicenseException

Parameters


sessionHandle String Session Handle

optParam Class Object of the LogoutOptionalParam class containing optionalparameters for the logout API.

response Class Object of the LogoutResponse class.


Returns

There are no return parameters.

Exception Handling


2.8. logout 77





n RT_INTERNAL_ERR




n RT_ERR_IN_LICENCE_RELEASE


See Also:

Sample Code - logout (Java)

2.8.4. logout (.NET)


Format

public void logout (


LogoutOptionalParam optParam,

LogoutResponse response)

Parameters


sessionHandle String Session Handle

optParam Class Object of the LogoutOptionalParam class containing optionalparameters for the logout API.

response Class Object of the LogoutResponse class.


Returns


Exception Handling





n RT_INTERNAL_ERR







See Also:

Sample Code - logout (.NET)

2.8.5. scr_logout (C)


Format

int scr_logout(

char *sessionHandle,

scr_LogoutOptionalParam_t *optParam,

scr_LogoutResponse_t **response)

Parameters


sessionHandle char* Session Handle

optParam scr_LogoutOptionalParam_t* Structure of the type scr_LogoutOptionalParam_t(C) containing optional parameters for the logoutAPI.

response scr_LogoutResponse_t** Structure of the type scr_LogoutResponse_t (C)containing response of the logout API.

Returns

The status code RT_SUCCESS is returned if successful. Otherwise, it will return the following errorcodes.




2.8. logout 79



n RT_ERR_IN_LOCKING

n RT_INTERNAL_ERR



n RT_ERR_IN_LICENSE_GEN









n RT_ERR_SSL_CACERT




See Also:

Sample Code - scr_logout (C)

2.9. releaseLicenseClientReleases all the resources in use.

For on-premise feature level licensing, this API pushes all the usage to Sentinel Cloud Connectand cleans all the connected stores.

2.9.1. Description

This API performs the following functions:

n De-initializes the Cloud Run-time; and releases thememory allocated to all its components.

n Sends pending usage logs to the Cloud Connect.

n After calling releaseLicenseClient, Run-time attempts to send usage data to Cloud Connect forthe period specified by the ServerConnectionTimeout property. After the specified period, the

usage is lost in the case of Cloud deployments. For on-premise deployments, the usage dataremains available in the persistent store in the encrypted format.


Call the acquireLicenseClient API again after calling this API and before calling other APIs.

In the case of Java and .NET, objects that contain the Cloud Run-time instance become invalidafter the releaseLicenseClient API has been called.

2.9.3. releaseLicenseClient (Java)

Format

public static void releaseLicenseClient()

throws LicenseException

Parameters

There are no input parameters for this function.

Returns


Exception Handling


n RT_ERR_IN_CRT_CLEANUP



See Also:

Sample Code - releaseLicenseClient (Java)

2.9.4. releaseLicenseClient (.NET)

Format

public static void releaseLicenseClient()

Parameters


Returns




Exception Handling


n RT_ERR_IN_CRT_CLEANUP




See Also:

Sample Code - releaseLicenseClient (.NET)

2.9.5. scr_releaseLicenseClient(C)

Format

int scr_releaseLicenseClient()

Parameters


Returns

The status code RT_SUCCESS is returned if successful. Otherwise, it will return the following errorcodes:



n RT_ERR_IN_LOCKING

n RT_INTERNAL_ERR











n RT_ERR_SSL_CACERT



See Also:

Sample Code - scr_releaseLicenseClient (C)


Chapter 3:Classes/Structures

This section describes the following:

n Classes for Java and .NET

n Structures for C

In this documentation, the .NET and Java classes correspond to C structures.

The available classes/structures are:

3.1. LicenseRuntime 86

3.2. FeatureNode 87

3.3. Format 91

3.4. Scope 96

3.5. Entitlement 103

3.6. LicenseAttribute 105

3.7. Product 110

3.8. Feature 112

3.9. License 116

3.10. Concurrency 118

3.11. GetInfoOptionalParam 121


3.13. Attributes 126

3.14. LoginOptionalParam 130

3.15. LoginResponse 133

3.16. LogoutOptionalParam 137

3.17. LogoutResponse 139

3.18. RefreshSessionOptionalParam 141

3.19. RefreshSessionResponse 142

3.20. GetIdentityOptionalParam 144

3

86 Chapter 3: Classes/Structures

3.21. GetIdentityResponse 145

3.22. TransferOptionalParam 147

3.23. TransferResponse 150

3.24. Features 151

3.25. AcquireClientOptionalParam 152

3.26. The AcquireClientResponse Class 153

3.27. Configuration 154

3.28. LicenseException 159

3.1. LicenseRuntimeThe LicenseRuntime class is themain class of Cloud Run-time SDK. It enables the licensed applicationto perform various functions, such as initialization, authentication, authorization, and de-initializationof the Cloud Run-time.

LicenseRuntime does not exist in the C interface of Cloud Run-time.

The diagram below depicts APIs in each category.

Cloud Run-time APIs

The table below provides a quick description of the APIs:

Category API Description

Initialization acquireLicenseClient Obtains an instance of the Cloud Run-time.

Authentication getIdentity Authenticates a user by requesting authentication cookie,identity, and customer reference ID from Cloud Connect.

Category API Description

This API is available only for on-premise feature levellicensing, implemented with authentication. To usethis API, an authentication system should beintegrated with Sentinel Cloud. Please contactSafeNet for integration-related details.

Authorization transfer Detaches licenses, returns licenses, applies license update,and syncs usage with Cloud Connect.

login Authorizes a user by requesting a license from the CloudConnect.

logout Releases the license acquired by the user.

getInfo Retrieves information about entitlements and features for agiven user.Also retrieves fingerprint and current license state of on-premisemachines.

refreshSession Refreshes a concurrent session.

This API is applicable only for cloud licensing.

De-initialization releaseLicenseClient Releases the instance of the Cloud Run-time.

LicenseRuntime is a singleton class, and internally it ensures that the various components ofCloud Run-time are initialized at most once. The application must retrieve an instance of theLicenseRuntime class by using the acquireLicenseClient API.

3.2. FeatureNodeProvides feature ID or feature name to Cloud Run-time for authorization.

Interfaces

3.2.1. The SaaSFeatureNode Class (Java) 88

3.2.2. The SaaSFeatureNode Class (.NET) 89

3.2.3. scr_FeatureNode_t (C) 91

3.2. FeatureNode 87


3.2.1. The SaaSFeatureNode Class (Java)

This class is used to provide feature ID or feature name to Cloud Run-time for authorization.

Authorization Criteria

n For Cloud: The authorization is done only on feature ID, so you must provide feature ID inthis class/structure. It is optional to provide feature name because it is not considered forauthorization.

n For On-premise: The authorization is done either on feature ID or on feature name. Youshould provide only one of these feature identifiers; otherwise an error will be returned. If avalid feature name is given, the feature ID should be zero or less than zero. If a valid featureID is given, feature name should be NULL.

Constructors

The constructors of this class are given below:

Constructor Syntax Description Parameters

Default publicSaaSFeatureNode()

When using thisconstructor, the applicationmust call APIs setFeatureIdand setFeatureName beforeproviding feature nodeobject to the Cloud Run-time API.

None

Constructor withfeature Id asargument

publicSaaSFeatureNode(intiFeatureId)

There is no need to call anyother API when using thisconstructor. Thisconstructor does notrequire feature name.

n iFeatureId -Identifier of thefeature forwhichauthorizationhas beenrequested.

Constructor withfeature Id andfeature name asarguments

publicSaaSFeatureNode(intiFeatureId,stringstrFeatureName)

There is no need to call anyother API when using thisconstructor.


n strFeatureName- A user-friendlyname of thefeaturespecifying itsfunctionality orother usefulinformation.


Constructor available only for on-premise applications

Constructor withfeature name asargument

publicSaaSFeatureNode(StringstrFeatureName)

strFeatureName - Auser-friendly name ofthe feature specifyingits functionality orother usefulinformation.

Functions

The following table describes the public interfaces of this class.

Name\Syntax Description Parameters Returns

setFeatureNamepublic voidsetFeatureName(StringstrFeatureName)

Sets feature namevalue of the featurenode. This value is aspecial name given tocorresponding featureID which can be used todefine functionality ofthe feature ID.


None

getFeatureNamepublic StringgetFeatureName()

Gets the feature nameof the feature node.

None Feature name

setFeatureIdpublic voidsetFeatureId(intiFeatureId)

Sets feature ID of thefeature node.

iFeatureId – Anidentifier of the featurefor which authorizationhas been requested.

None

getFeatureIdpublic intgetFeatureId()

Gets the feature ID ofthe feature node.

None Feature ID

3.2.2. The SaaSFeatureNode Class (.NET)

This class is used to provide feature ID or feature name to Cloud Run-time for authorization.



3.2. FeatureNode 89



Constructors



Default publicSaaSFeatureNode();

When using thisconstructor, the applicationmust call APIs setFeatureIdand setFeatureName beforeproviding feature nodeobject to the Cloud Run-time API.

None

Constructor withfeature Id asargument

publicSaaSFeatureNode(intiFeatureId);

There is no need to call anyother API when using thisconstructor. Thisconstructor does notrequire feature name.


Constructor withfeature Id andfeature name asarguments

publicSaaSFeatureNode(int iFeatureId,stringstrFeatureName);

There is no need to call anyother API when using thisconstructor.


n strFeatureName- A user-friendlyname of thefeaturespecifying itsfunctionality orother usefulinformation.

Constructor available only for on-premise applications

Constructor withfeature name asargument

publicSaaSFeatureNode(StringstrFeatureName);


Functions

The following table describes the public interfaces of this class.

Properties Description

strFeatureNamepublic StringstrFeatureName

Gets or sets the feature name value of the feature node. This value is a specialname given to corresponding feature ID which can be used to definefunctionality of the feature ID.

iFeatureIdpublic intiFeatureId

Gets or sets the feature ID of the feature node.

3.2.3. scr_FeatureNode_t (C)

This structure is used to provide feature ID or feature name to Cloud Run-time for authorization.




Syntax

typedef struct scr_FeatureNode {

char *FeatureName;

int FeatureId;

} scr_FeatureNode_t;

Members

Member Data Type Description

FeatureName char* A user-friendly name of the feature specifying its functionalityor other useful information.

FeatureId int ID of the feature for which authorization has been requested.

3.3. FormatSets the output format (level of detail) of the getInfo API.

3.3. Format 91


Interfaces

3.3.1. The Format Class (Java) 93

3.3.2. The Format Class (.NET) 94

3.3.3. scr_Format_t (C) 95

3.3.1. The Format Class (Java)

The Format class is used to set the output format (level of detail) of the getInfo API.

Format Type

The format type specifies the level of detail you want to obtain from the getInfo API, and how todisplay the obtained information.

The following table describes the available format types:

Format Type Value Description

HIERARCHY_INFO 1 Returns the entitlement ID, product name, feature ID,and feature name.This is applicable only for cloud applications.

FEATURE_AUTHORIZATION 2 Returns the usability flag, usability status, and time zone;in addition to the information returned by HIERARCHY_INFO. The usability flag returns a Boolean value to showwhether the usability status is available (true) or not(false).This is applicable only for cloud applications.

FEATURE_DETAILS 4 Shows detailed information of a feature in addition to theinformation returned by FEATURE_AUTHORIZATION.

n In the case of Cloud deployment, the featureinformation can include licensemodel, start date,end date, concurrency, prepaid count and otherlicense attributes.

n In the case of On-premise deployment, the featureinformation does not include start date.

MACHINE_FINGERPRINT 8 Returns the unique fingerprint of an on-premisemachine.This is applicable only for on-premise applications.

CURRENT_LICENSE_STATE 16 Returns a snapshot of all the license available on anisolated on-premisemachine.This is applicable only for on-premise entitlementscreated with entitlement level feature caching mode.

If no value or a value other than the above formats is specified, by default HIERARCHY_INFO(1) is returned for Cloud applications and FEATURE_DETAILS (4) is returned for on-premiseapplications.

Constructors



Default public Initializes the Format class. None

3.3. Format 93


Constructor Syntax Description ParametersFormat();

After using this constructor, the application must call thefollowing API to set the desired format type, beforeproviding Format object to a Cloud Run-time API.

n setFormat (for Java)

The default format type is FEATURE_DETAILS.

Functions

The following table describes the public interfaces of the Format class.


setFormatpublic voidsetFormat(Integerformat);

Sets the format type. An integer to specifythe format. See FormatType for the list of validvalues.

None

getFormatpublic IntegergetFormat();

Gets the format type. None Format Type

3.3.2. The Format Class (.NET)

The Format class is used to set the output format (level of detail) of the getInfo API.

Format Type

The format type specifies the level of detail you want to obtain from the getInfo API, and how todisplay the obtained information.






n In the case of Cloud deployment, the feature


information can include licensemodel, start date,end date, concurrency, prepaid count and otherlicense attributes.





Constructors



Default publicFormat();

Initializes the Formatclass.After using this constructor, the application must call thefollowing API to set the desired format type, beforeproviding Format object to a Cloud Run-time API.

n FormatStyle

The default format type is FEATURE_DETAILS.

None

Functions

The following table describes the public interfaces of the Format class.


FormatStylepublic Int32FormatStyle

Gets or sets the format type of the getInfo API. See Format Type forthe list of valid values.

3.3.3. scr_Format_t (C)

The scr_Format_t structure is used to set the output format (level of detail) of the scr_getInfo API.

Syntax

typedef struct scr_Format {

int FormatStyle;

3.3. Format 95


} scr_Format_t;

Members


FormatStyle int Format type of the scr_getInfo API. See scr_FormatType_t (C)for the list of valid values.

3.4. ScopeDefines the scope of the information that you want to retrieve by using the getInfo API.

Interfaces

3.4.1. The Scope Class (Java) 97

3.4.2. The Scope Class (.NET) 99

3.4.3. scr_Scope_t (C) 101

3.4.1. The Scope Class (Java)

This class is used to define the scope of the information that you want to retrieve by using the getInfoAPI.

Constructors

The following table lists the constructors of the Scope class:


Default publicScope()

After using this constructor, the application must callthe add API before providing the scope object tothe Cloud Run-time API.

None

Functions

The following table describes the functions of the Scope class.


addpublic void add(String EID,StringproductName,SaaSFeatureNodefeatureNode)throwsLicenseException

This method isused to set thecombination ofrequestparameter forgetInfo API.See: PossibleCombinations

n EID - Unique entitlement ID usedto identify an entitlement.

n productName - Combination ofproduct name and version. It isspecified in the format:<productname>^<version>.For example, Trial^1.0.

n featureNode - Object of theSaaSFeatureNode class containingthe feature to be authorized.

None

Possible Combinations

Following are the combinations for the request parameters of the getInfo API, in the case of Cloud andOn-premise applications:

Cloud

EID productName

feature Id*

as specified in

SaaSFeatureNode

Result

Null Null Null Information of all features of allproducts in all entitlements related tothat customer and user.

Not null Null Null Information of all features andproducts for a given EID.

3.4. Scope 97


EID productName

feature Id*

as specified in

SaaSFeatureNode

Result

Not null Not null Null Information of all features for thegiven productName and EID.

Not null Not null Valid feature ID Information for the given feature Id,productName, and EID.

Null Not null Valid feature ID Information for the given feature Idand productName in all entitlements.

Null Null Valid feature ID Information for the given feature Id inall the products and entitlements.

Not null Null Valid feature ID Information for given featureId in allthe products for the given EID.

*For Cloud applications, only feature Id is considered for authorization. The feature name, ifprovided, is ignored.

On-premise

EID productName **SaaSFeatureNode Result Comments

Null Null Null Information of all thefeatures across allentitlements related tothat customer anduser.

Null Null Contains either featureId or feature name

Information for thegiven feature Id in allthe products andentitlements.

NotNull

Null Null Information of allfeatures for a given EID.

In case of noconnectivity in FeatureLevel mode, EIDprovided will beignored.

NotNull

Null Contains eitherfeatureId or featurename

Information for givenfeature id/name in allthe products for thegiven EID.


** For On-premise applications, only one of the values—either feature Id or feature name—shouldbe passed in SaaSFeatureNode. If both the values are passed or if both the values are incorrect, anerror is returned.

The results vary depending upon the Format Type.

3.4.2. The Scope Class (.NET)

This class is used to define the scope of the information that you want to retrieve by using the getInfoAPI.

Constructors

The following table lists the constructors of the Scope class:


Default publicScope()

After using this constructor, the application must callthe Add API before providing the scope object tothe Cloud Run-time API.

None

Functions

The following table describes the functions of the Scope class.


Addpublic void Add(String EID,StringproductName,SaaSFeatureNodefeatureNode)

This methodis used to setthecombinationof requestparameter forgetInfo API.See: PossibleCombinations

n EID - Unique entitlement ID used toidentify an entitlement.

n productName - Combination of productname and version. It is specified in theformat:<productname>^<version>

For example, Trial^1.0.n featureNode - Object of the

SaaSFeatureNode class containing thefeature to be authorized.

None



Cloud

EID productName

feature Id*

as specified in

SaaSFeatureNode

Result

Null Null Null or -1 Information of all features of allproducts in all entitlementsrelated to that customer anduser.

Not null Null -1 Information of all features andproducts for a given EID.

3.4. Scope 99


EID productName

feature Id*

as specified in

SaaSFeatureNode

Result

Not null Not null -1 Information of all features for thegiven productName and EID.

Not null Not null Valid feature ID Information for the given featureId, productName, and EID.

Null Not null Valid feature ID Information for the given featureId and productName in allentitlements.

Null Null Valid feature ID Information for the given featureId in all the products andentitlements.

Not null Null Valid feature ID Information for given featureIdin all the products for the givenEID.

**For Cloud applications, only feature ID is considered for authorization. The feature name, ifprovided, is ignored.

On-premise





NotNull



NotNull




* For On-premise applications, only one of the values—either feature Id or feature name—should bepassed in SaaSFeatureNode. If both the values are passed or if both values are incorrect, an error isreturned.

The results vary depending upon the Format Type.

3.4.3. scr_Scope_t (C)

This structure is used to define the scope of the information that you want to retrieve by using thescr_getInfo API.

Syntax

typedef struct scr_Scope{

char *EID;

char *ProductName;

scr_FeatureNode_t *FeatureNode;

struct scr_Scope_t *Next;

} scr_Scope_t;

Members


EID char* Unique entitlement ID used to identify an entitlement

ProductName char* Combination of product name and version. It is specified in theformat: <productname>^<version>.For example, Trial^1.0.

FeatureNode scr_FeatureNode_t

The structure of type scr_FeatureNode_t (C) containing thefeature to be authorized.

Next scr_Scope_t* Next element of scr_Scope_t.

Only single scope is supported currently. So Next shouldbe NULL.



Cloud

EID productName

feature Id*

as specified in

SaaSFeatureNode

Result

Null Null -1 Information of all features of allproducts in all entitlementsrelated to that customer and

3.4. Scope 101


EID productName

feature Id*

as specified in

SaaSFeatureNode

Result

user.

Not null Null -1 Information of all features andproducts for a given EID.

Not null Not null -1 Information of all features for thegiven productName and EID.

Not null Not null Valid feature ID Information for the given featureId, productName, and EID.

Null Not null Valid feature ID Information for the given featureId and productName in allentitlements.

Null Null Valid feature ID Information for the given featureId in all the products andentitlements.

Not null Null Valid feature ID Information for given featureIdin all the products for the givenEID.

*For Cloud applications, only feature Id is considered for authorization. The feature name, ifprovided, is ignored.

On-premise





NotNull



NotNull



In case of noconnectivity in FeatureLevel mode, EIDprovided will be


ignored.

** For On-premise applications, only one of the values—either feature Id or feature name—shouldbe passed in SaaSFeatureNode. If both the values are passed or if both values are incorrect, an erroris returned.

The results vary depending upon the scr_FormatType_t (C).

3.5. EntitlementContains all the entitlements returned by the getInfo API.

Interfaces

3.5.1. The Entitlement Class (Java) 104

3.5.2. The Entitlement Class (.NET) 104

3.5.3. scr_Entitlement_t (C) 105

3.5. Entitlement 103


3.5.1. The Entitlement Class (Java)

This class contains all the entitlements returned by the getInfo API.

Functions

This section describes the public functions of the Entitlement class:


getEID

public StringgetEID()

Retrieves the entitlement ID. None String containingentitlement ID.

getProductspublicVector<Product>getProducts()

Retrieves details of theproducts belonging to anentitlement.

None An object of theProduct class.

getTimeZonePublic StringgetTimeZone

Retrieves time zone ofcustomer.

None String containing timezone value.

Related Topics:

getInfo

3.5.2. The Entitlement Class (.NET)

This class contains all the entitlements returned by the getInfo API.

Functions

This section describes the public functions of the Entitlement class:


EID

public String EID Retrieves the entitlement ID.

products

publicList<Product>products

Retrieves an object of the Product class, containing details of theproducts belonging to an entitlement.

TimeZonePublic StringTimeZone

Retrieves time zone of customer.

Related Topics:

getInfo

3.5.3. scr_Entitlement_t (C)

This structure contains all the entitlements returned by the scr_getInfo API.

Syntax

typedef struct scr_Entitlement{

char *EID;

char *TimeZone;

scr_Product_t *Products;

struct scr_Entitlement_t *Next;

} scr_Entitlement_t;

Members


EID char* String containing entitlement ID.

TimeZone char* String containing the time zone value.

Products scr_Product_t*

Structure of type scr_Product_t (C), containing details of theproducts belonging to an entitlement.

Next scr_Entitlement_t*

Next element of scr_Entitlement_t.

3.6. LicenseAttributeContains license attribute information returned by the getInfo API, as a Key-Value pair. For everylicense attribute name, the corresponding value is stored.

There is an exception for Concurrent licensemodels. To retrieve concurrency attributes, youwill need to fetch the concurrency from the Feature class/structure.

License Attributes

This section provides a comprehensive list of all the available license attributes. A licensemodelusually contains a combination of these attributes. Based on these attributes, you may even defineyour own licensemodels that meet your business requirements.

License Attribute Description

Time (License Validity)

Start Date The license start date and time. If a beginning date is chosen for a license, thefeature can not be used before that date and time. You can specify date in thedd/mm/yyyy format, and time in the hours:minutes format.

DST is automatically applied to the license start/end date according tothe customer time zone. The DST adjustment is applicable for thedates lying in years 2012 and 2013*.




*This is because DST information is available till year 2013 only.

End Date The license expiration date and time. The license expires when the end date isreached. You can specify date in the dd/mm/yyyy format, and time in thehours:minutes format.The end date can also be set to 'No Limit' (never expire).

DST is automatically applied to the license start/end date according tothe customer time zone. The DST adjustment is applicable for thedates lying in years 2012 and 2013*.*This is because DST information is available till year 2013 only.

Grace

Grace Limit The duration of grace period.The additional number of days/times the featurecan be used after its license has expired/exhausted.

n For subscription licenses, range is 1 to 365.n For prepaid licenses, range is 1 to 2147483647.

Default Value: 0 (to indicate 'no grace')

Measurement Unit The unit to specify the grace limit.Default Value: Days for subscription and Count for prepaid

Maximum Usage Limit

Maximum UsageLimit

Themaximum number of times a feature can be used. Its range is 1 to2147483647.Default Value: 100

Concurrent Limit

Concurrent Limit Themaximum number of concurrent instances allowed for a feature.The Concurrent Limit for a feature should be in the range 1-32752.Default Value: 100

Each login to feature is a session.

Instance Counting Specifies how concurrent instances are counted. Select what is to be countedas a concurrent instance.The criteria of counting concurrent instances, which can be one of thefollowing:

n Per Login - Count each login request as an instance. If the same userlogins to a featuremultiple times, each login will consume oneconcurrency limit.

n Per Identity - Count each user as an instance. All the login requests bythe same user ID are counted as an instance, and consume only oneconcurrency limit.

n Per Identity Per Station - Count each user-machine pair as one session.All the login requests by the same user from the samemachine are


counted as one session, and consume only one concurrency limit.Concurrency is counted as follows:

n A user accessing the single instance application on the samemachine is counted as ONE count.

n A user accessing themultiple instances of an application on thesamemachine is counted as ONE count.

n The same user accessing themultiple instances of the applicationon multiple machines is counted as N usage, where N is thenumber ofmachines.

n If the user logs on to an application from a terminal server, itcontributes to an additional count.

Concurrency Support for Deployment ModelsThe following table specifies which counting types are supported for whichdeployment type:

Counting Type Cloud On-premiseEntitlement Level

On-premiseFeature Level

Per Login Yes Yes No

Per Identity Yes No No

Per Identity perStation

No No Yes

Default Value: Per Login

Usage Type

Usage Type Data Aggregation for tracking usage. It can be of the following types:

n Count Based: Each login-logout pair is counted as one execution.n Time Based: Duration of each login session is aggregated.

Default Value: Varies according to licensemodel type

Vendor Attribute

Vendor Attribute Stores a vendor-defined value. For example, you can specify employee role ordata download speed in this attribute.You can query vendor attribute values in a protected application by using thegetInfo Run-time API, and define application logic based on the outcome.EMS also allows generating the following reports based on the value specifiedin vendor attribute:

n Custom Vendor Attribute Reportn Feature Usage Based on Vendor Attribute Report

You can enter up to 255 alphanumeric characters in this field.

A vendor attribute is not used by Cloud Connect in licenseenforcement.

Default Value: Null




Capacity Attribute

Capacity Attribute Used to enable processing of capacity values recorded by an application forpostpaid features. You must set Capacity Attribute in EMS if you want to benotified when your customers approach or reach a specified limit.You can define Capacity Attribute only for postpaid licensemodels.The allowed range is 1 to 2147483647.Default Value: NullMonitoring Usage and Generating NotificationsIt is the limit beyond which you may want to monitor the feature usage. Youcan configure e-mail notifications to be sent when the Peak Capacity of afeature approaches or reaches the limit set in Capacity Attribute. The relatednotification rules available in EMS are: Capacity Peak Exceeded and CapacityPeak Approaching.In addition, you can also use the getInfo Run-time API to query capacityinformation, and implement decision making based on the response. Forexample, you can throwwarning messages to user from within the applicationon exceeding the limit set in Capacity Attribute.

n For more details about Capacity, refer to section AboutCapacity.

n The Capacity feature is supported only for on-premiseapplications.

Key Attributes of a License Model

Interfaces

3.6.1. The LicenseAttribute Class (Java) 109

3.6.2. The LicenseAttribute Class (.NET) 109

3.6.3. scr_LicenseAttribute_t (C) 110

3.6.1. The LicenseAttribute Class (Java)

This class contains license attribute information returned by the getInfo API. This class contains name-value pair, storing information of attribute name and the corresponding value. For information onlicense attributes, please refer to the section License Attributes .

There is an exception for Concurrent licensemodels. To retrieve concurrency attributes, youwill need to call the getConcurrency function of the Feature class.

Functions

This section describes the public functions of the LicenseAttribute class:


getName

public String getName()

Retrieves thename of thelicenseattribute.

None String containing licenseattribute name.

getValue

public String getValue()

Retrieves thevalue oflicenseattribute,such as StartDate andEnd Date.

None String containingattribute value.

Related Topics:

getInfo

3.6.2. The LicenseAttribute Class (.NET)

This class contains license attribute information returned by the getInfo API. This class contains name-value pair, storing information of attribute name and the corresponding value. For information onlicense attributes, please refer to the section License Attributes .

There is an exception for Concurrent licensemodels. To retrieve concurrency attributes, youwill need to call the getConcurrency function of the Feature class.

Functions

This section describes the public functions of the LicenseAttribute class:


Name



Properties Descriptionpublic String Name Retrieves the name of the license attribute.

Valuepublic String Value Retrieves the value of license attribute.

Related Topics:

getInfo

3.6.3. scr_LicenseAttribute_t (C)

This structure contains license attribute information returned by the scr_getInfo API. This structurecontains name-value pair, storing information of attribute name and the corresponding value. Forinformation on license attributes, please refer to the section License Attributes .

There is an exception for Concurrent licensemodels. To retrieve concurrency attributes, youwill need to get the concurrency of the Feature structure.

Syntax

typedef struct scr_LicenseAttribute {

char *Name;

char *Value;

struct scr_LicenseAttribute_t *Next;

} scr_LicenseAttribute_t;

Members


Name char* String containing license attribute name.

Value char* String containing the attribute value.

Next scr_LicenseAttribute_t*

Next element of scr_LicenseAttribute_t.

3.7. ProductContains all the products returned by the getInfo API.

Interfaces

3.7.1. The Product Class (Java) 111

3.7.2. The Product Class (.NET) 111

3.7.3. scr_Product_t (C) 112

3.7.1. The Product Class (Java)

This class contains all the products returned by the getInfo API.

Functions

This section describes the public functions of the Product class:


getFeatures

publicVector<Feature>getFeatures()

Retrieves the feature list. None An object of the Featureclass, containing list offeatures.

getProductName

public StringgetProductName()

Retrieves the name of theproduct, in the following format:<productname>^<version>.Here, <productname> is thename of product and<version> is the version of theproduct.Example: Trial^1.0.

None String containingproduct name andversion.

Related Topics:

getInfo

3.7.2. The Product Class (.NET)

This class contains all the products returned by the getInfo API.

Functions

This section describes the public functions of the Product class:


features

publicList<Feature>features

Retrieves an object of the Feature class, containing the featurelist.

ProductName

public StringProductName

Retrieves the name of the product, in the following format:<productname>^<version>.Here, <productname> is the name of product and<version> is the version of the product.

3.7. Product 111



Example: Trial^1.0.

Related Topics:

getInfo

3.7.3. scr_Product_t (C)

This structure contains all the products returned by the scr_getInfo API.

Syntax

typedef struct scr_Product{

char *product_name;

scr_Feature_t *Feature;

struct scr_Product_t *Next;

} scr_Product_t;

Members


product_name char* String containing product name and version, in the followingformat:<productname>^<version>.Here, <productname> is the name of product and<version> is the version of the product.Example: Trial^1.0.

Feature scr_Feature_t*

The structure in which information will be returned. Pointer toscr_Feature_t (C), containing feature-specific information.

Next scr_Product_t*

Next element of scr_Product_t.

3.8. FeatureContains features returned by the getInfo API.

Interfaces

3.8.1. The Feature Class (Java) 113

3.8.2. The Feature Class (.NET) 114

3.8.3. scr_Feature_t (C) 115

3.8.1. The Feature Class (Java)

This class contains features returned by the getInfo API.

Functions

This section describes the public functions of the Feature class:


getConcurrency

public ConcurrencygetConcurrency()

Retrievesconcurrencydetails.

None An object of the Concurrency class.

getUsabilityStatus

public StringgetUsabilityStatus()

Retrieves theusabilitystatus offeature.

None String containing usability status. It couldbe:

n Available: License is ready for use.n An error string: License is not

available.

IsUsable

public BooleanIsUsable()

Specifies ifthe feature isusable ornot.

None One of the following:

n True: License is usable.n False: License is not usable.

getLicense

public License getLicense() Returnslicense-specificinformation.

None An object of the License class, containinglicense-specific information.

getFeatureId

public Integer getFeatureId()

Retrieves thefeature Id.

None Feature ID.

getFeatureName

public StringgetFeatureName()

Retrieves thename offeature.

None String containing feature name.

getNotifications

Public int getNotifications Retrievesnotificationdetails forthe feature,if any.

None Integer data type.Use a bitwise AND operation and theNotification enumerator to determine thetype of notification. TheNotificationenumerator is of enumerated data type.Possible values are:

3.8. Feature 113



n GRACE: Indicates that the feature isin grace period.

An example to check notification:

If ( feature.getNotifications() &

Notification.GRACE.getCode() ==

Notification.

GRACE.getCode() )

{

//Handle grace notification

here

}

The getNotifications function is not applicable for On-premise applications.

Related Topics:

getInfo

3.8.2. The Feature Class (.NET)

This class contains features returned by the getInfo API.

Functions

This section describes the public functions of the Feature class:


Concurrencypublic ConcurrencyConcurrency

Retrieves an object of the Concurrency class, containingconcurrency data.

UsabilityStatuspublic StringUsabilityStatus

Retrieves the usability status of feature. The status couldbe:

n Available: License is ready for use.n An error string: License is not available.

IsUsablepublic StringIsUsable

One of the following:

n True: License is usable.n False: License is not usable.

Licensepublic LicenseLicense

An object of the License class, containing license-specificinformation.


FeatureIdpublic int FeatureId Retrieves the feature Id.

FeatureNamepublic StringFeatureName

Retrieves the name of feature.

Notifications

Public int Notifications Integer data type.Use a bitwise AND operation and theNotificationenumerator to determine the type of notification. TheNotification enumerator is of enumerated data type.Possible values are:

n GRACE: Indicates that the feature is in grace period.

An example to check notification:

If ( feature. Notifications & Notification.GRACE ==

Notification.GRACE )

{

//Handle grace notification here

}

Related Topics:

getInfo

3.8.3. scr_Feature_t (C)

This structure contains features returned by the scr_getInfo API.

Syntax

typedef struct scr_Feature{

int FeatureId;

char *FeatureName;

int IsUsable;

char *UsabilityStatus;

int Notifications;

scr_Concurrency_t *Concurrency;

scr_License_t *License;

scr_Feature_t *Next;

} scr_Feature_t;

3.8. Feature 115


Members


FeatureId int String containing feature Id.

FeatureName char* String containing feature name.

IsUsable int One of the following:

n 1: License is usable.n 0: License is not usable.

UsabilityStatus char* String containing usability status. It could be:

n Available: License is ready for use.n An error string: License is not available.

Notifications int Uses a bitwise AND operation and theNotificationenumerator to determine the type of notification. TheNotification enumerator is of enumerated data type.Possible values are:

n GRACE: Indicates that the feature is in grace period.

Concurrency scr_Concurrency_t*

The structure in which information will be returned. Pointerto scr_Concurrency_t (C), containing concurrency data.

License scr_License_t* The structure in which information will be returned. Pointerto scr_License_t (C), containing license-specific information.

Next scr_Feature_t* Next element of scr_Feature_t.

Notifications are not applicable for On-premise applications.

3.9. LicenseContains information of the licenses returned by the getInfo API.

Interfaces

3.9.1. The License Class (Java) 117

3.9.2. The License Class (.NET) 117

3.9.3. scr_License_t (C) 118

3.9.1. The License Class (Java)

This class contains information of the licenses returned by the getInfo API.

Functions

This section describes the public functions of the License class:


getLicenseType

public StringgetLicenseType()

Retrieves thelicensemodel type.

None String containing type oflicensemodel, which can be:

n Prepaid-Countn Concurrent-

Subscription-Countn Concurrent-

Subscription-Timen PostPaid-Countn PostPaid-Timen Subscription-Countn Subscription-Time

getLicenseAttributes

publicVector<LicenseAttribute>getLicenseAttributes()

Retrieve thelicenseattribute list.

None One or more object of theLicenseAttribute class.

Related Topics:

getInfo

3.9.2. The License Class (.NET)

This class contains information of the licenses returned by the getInfo API.

Functions

This section describes the public functions of the License class:


LicenseTypepublic StringLicenseType

Retrieves the type of licensemodel, which can be:

n Prepaid-Countn Concurrent-Subscription-Countn Concurrent-Subscription-Timen PostPaid-Countn PostPaid-Timen Subscription-Count

3.9. License 117



n Subscription-Time

licenseAttributespublicList<LicenseAttribute>licenseAttributes

Returns one or more object of the LicenseAttribute class,containing the license attribute list.

Related Topics:

getInfo

3.9.3. scr_License_t (C)

This structure contains information of the licenses returned by the scr_getInfo API.

Syntax

typedef struct scr_License{

char *LicenseType;

scr_LicenseAttribute_t *LicenseAttribute;

} scr_License_t;

Members


LicenseType char* String containing the type of licensemodel, which can be:

n Prepaid-Countn Concurrent-Subscription-Countn Concurrent-Subscription-Timen PostPaid-Countn PostPaid-Timen Subscription-Countn Subscription-Time

LicenseAttribute scr_LicenseAttribute_t

The structure in which information will be returned.Pointer to scr_LicenseAttribute_t (C), containing thelicense attribute list.

3.10. ConcurrencyContains the concurrency information returned by the getInfo API.

Interfaces

3.10.1. The Concurrency Class (Java) 119

3.10.2. The Concurrency Class (.NET) 120

3.10.3. scr_Concurrency_t (C) 121

3.10.1. The Concurrency Class (Java)

This class contains the concurrency information returned by the getInfo API.

Functions

This section describes the public functions of the Concurrency class:


getCountDefinition

public CountgetCountDefinition()

Retrieves thetype ofconcurrency.

None Enumerated data type.Possible values are:

n STATION: Concurrencydue to number ofmachines.

n LOGIN: Concurrency dueto number of loginsessions.

n IDENTITY: Concurrencydue to number of users.

Currently, for Cloudapplications, onlyLOGIN and IDENTITY aresupported. For On-premise applicationsdeployed withEntitlement Levelfeature caching mode,only LOGIN issupported. For On-premise applicationsdeployed with FeatureLevel feature cachingmode, only STATION issupported.

getConcurrentLimit

public IntegergetConcurrentLimit()

Retrieves theconcurrentlimit.

None Integer containing concurrentlimit.

getActiveSessions

public IntegergetActiveSessions()

Retrieves thenumber ofcurrently-active

None Integer containing the numberof active concurrent instances.This information can beretrieved for cloud and on-

3.10. Concurrency 119



concurrentinstances.

premise feature leveldeployments, in connectedmode. For on-premiseentitlement level deployment,0 value is returned.

Related Topics:

getInfo

3.10.2. The Concurrency Class (.NET)

This class contains the concurrency information returned by the getInfo API.

Functions

This section describes the public functions of the Concurrency class:


CountDefinitionpublic CountCountDefinition

Retrieves the type of concurrency.Possible values are:

n STATION: Concurrency due to number ofmachines.

n LOGIN: Concurrency due to number of loginsessions.

n IDENTITY: Concurrency due to number of users.

Currently, for Cloud applications, only LOGIN andIDENTITY are supported. For On-premiseapplications deployed with Entitlement Levelfeature caching mode, only LOGIN is supported.For On-premise applications deployed withFeature Level feature caching mode, only STATIONis supported.

ConcurrentLimitpublic Int32ConcurrentLimit

Retrieves the concurrent limit.

ActiveSessionspublic Int32ActiveSessions

Retrieves the number of active concurrent instances.This information can be retrieved for cloud and on-premise feature level deployments, in connected mode.For on-premise entitlement level deployment, 0 value isreturned.

Related Topics:

getInfo

3.10.3. scr_Concurrency_t (C)

The scr_Concurrency_t structure contains the concurrency information returned by the scr_getInfoAPI.

Syntax

typedef struct scr_Concurrency{

int ConcurrentLimit;

scr_Count_t CountDefinition;

int ActiveSessions;

} scr_Concurrency_t;

Members


ConcurrentLimit int Retrieves the concurrent limit.

CountDefinition scr_Count_t

Enumerated data type.Possible values are:

n STATION: Concurrency due to number ofmachines.n LOGIN: Concurrency due to number of login sessions.n IDENTITY: Concurrency due to number of users.

Currently, for Cloud applications, only LOGIN andIDENTITY are supported. For On-premise applicationsdeployed with Entitlement Level feature caching mode,only LOGIN is supported. For On-premise applicationsdeployed with Feature Level feature caching mode,only STATION is supported.

ActiveSessions int Retrieves the number of active concurrent instances.This information can be retrieved for cloud and on-premisefeature level deployments, in connected mode. For on-premiseentitlement level deployment, 0 value is returned.

3.11. GetInfoOptionalParamContains optional parameters for the getInfo API.

Interfaces

3.11.1. The GetInfoOptionalParam Class (Java) 122

3.11.2. The GetInfoOptionalParam Class (.NET) 122

3.11.3. scr_GetInfoOptionalParam_t (C) 122

3.11. GetInfoOptionalParam 121


3.11.1. The GetInfoOptionalParam Class (Java)

This class stores the optional parameters for the getInfo API.

Functions

This section describes the public functions of the GetInfoOptionalParam class:


getCapacityInterval

public void setCapacityInterval( intcapacityNotificationTimeWindow)

It is applicable only for on-premise applications.

Specifies thenumber ofhours forretrievingpeak capacityinformation

capacityNotificationTimeWindow -The last 'N' hours from when you wantto view list of features for which peakcapacity reached a specified value(Capacity Attribute). You can specify aninteger ranging from 0 to 1440.Capacity Attribute is a license attributedefined in EMS for features havingpostpaid licensemodel. For details, seesection Retrieving Peak CapacityInformation.

None

3.11.2. The GetInfoOptionalParam Class (.NET)

This class stores the optional parameters for the getInfo API.

Functions

This section describes the public functions of this class:


capacityInterval

public int capacityInterval

It is applicable onlyfor on-premiseapplications.

The last 'N' hours from when you want to view list of features forwhich peak capacity reached a specified value (Capacity Attribute).You can specify an integer ranging from 0 to 1440.Capacity Attribute is a license attribute defined in EMS for featureshaving postpaid licensemodel. For details, see section RetrievingPeak Capacity Information.

3.11.3. scr_GetInfoOptionalParam_t (C)

This structure contains optional parameters for the scr_getInfo (C) API.

Syntax

typedef struct scr_GetInfoOptionalParam

{

unsigned int CapacityInterval;

}scr_GetInfoOptionalParam_t;

Members


CapacityInterval

It isapplicable only foron-premiseapplications.

unsigned int The last 'N' hours from when you want to view list of features forwhich peak capacity reached a specified value (Capacity Attribute).You can specify an integer ranging from 0 to 1440.Capacity Attribute is a license attribute defined in EMS for featureshaving postpaid licensemodel. For details, see section RetrievingPeak Capacity Information.

3.12. GetInfoResponseContains list of all the features and entitlements returned by the getInfo API.

Interfaces

3.12.1. The GetInfoResponse Class (Java) 124

3.12.2. The GetInfoResponse Class (.NET) 125

3.12.3. scr_GetInfoResponse_t (C) 125



3.12.1. The GetInfoResponse Class (Java)

This class contains list of all the features and entitlements returned by the getInfo API.

Functions

This section describes the public functions of the GetInfoResponse class:


getFeatureInfoList

public Vector<Feature>getFeatureInfoList()

Retrieves list offeatures across allentitlements andproducts. Resultsvary depending uponthe provided formatand scope.

None List of features along with detailsof each feature.

getEntitlementList

publicVector<Entitlement>getEntitlementList()

Retrieves one ormore entitlement.The entitlementcontains one or moreproduct and productcontains one or morefeatures. The resultsmay vary dependingupon the providedformat and scope.

None One or more object of theEntitlement class.

fingerPrint

private StringfingerPrint

String containingmachine fingerprint.

It is applicableonly for on-premiseapplications.

None Machine fingerprint

currentLicenseState

private StringcurrentLicenseState

String containingcurrent license state.It is used to indicatewhether or notlicenses are availableon an on-premisemachine.

It is applicable

None Current license state


only for on-premiseapplicationscreated withentitlementlevel mode.

The getEntitlementList function is not applicable for On-premise applications.

3.12.2. The GetInfoResponse Class (.NET)

This class contains list of all the features and entitlements returned by the getInfo API.

Functions

This section describes the public functions of the GetInfoResponse class:


FeatureInfoList

Public List<Feature>FeatureInfoList

Retrieves list of features across all entitlements andproducts. Results vary depending upon the providedformat and scope.

entitlementList

public List<Entitlement>entitlementList

Returns one or more object of the Entitlement class,containing entitlement list. The entitlement contains oneor more product and product contains one or morefeatures. The results may vary depending upon theprovided format and scope.

FingerPrint

public String FingerPrint String containing machine fingerprint.


CurrentLicenseState

public StringCurrentLicenseState

String containing current license state. It is used toindicate whether or not licenses are available on an on-premisemachine.

It is applicable only for on-premise applicationscreated with entitlement level mode.

3.12.3. scr_GetInfoResponse_t (C)

This structure contains list of all the features and entitlements returned by the scr_getInfo (C) API.



Syntax

typedef struct scr_GetInfoResponse {scr_Feature_t *FeatureInfoList;

scr_Entitlement_t *EntitlementInfoList;

char *FingerPrint;

char *CurrentLicenseState;

} scr_GetInfoResponse_t;

Members


FeatureInfoList scr_Feature_t * Structure of the type scr_Feature_t (C), containing list offeatures across all entitlements and products. The resultsmay vary depending upon the provided format and scope.

EntitlementInfoList scr_Entitlement_t*

Structure of the type scr_Entitlement_t (C),containing listof entitlements. The entitlement contains one or moreproduct and product contains one or more features. Theresults may vary depending upon the provided format andscope.

It is applicable only for Cloud applications.

FingerPrint char* String containing machine fingerprint.


CurrentLicenseState char* String containing current license state. It is used to indicatewhether or not licenses are available on an on-premisemachine.

It is applicable only for on-premise applicationscreated with entitlement level mode.

3.13. AttributesSet of internal classes/objects/structures that define custom attributes. You can use customattributes to track and monetize the feature usage by customers. For example, you can specify howmuch bandwidth your customers are consuming, howmuch data is being stored or downloaded, andhowmany times a feature is being used.

The custom attributes are provided while calling a run-time API.

Currently, the custom attributes are provided only for the logout API.

Custom Attributes

usageCountMultiplier

It is a custom attribute that you can provide with the logout API. It stores the value of custom usageyou want to push in Cloud Connect database. This count specifies the number of executionsconsumed by a user during a session.

n Supported only for Count-based licenses.n Not supported for Concurrent licenses. The usage count does not increase the con-

currency count for a concurrent license.

n Postpaid licenses are supported to be eventually consistent (not always consistent).

Since the usageCountMultiplier attribute is passed at the logout time, it is possible forthe user to consumemore counts than allowed. Suppose a user is allowed 10 counts,and he consumes counts in the following manner: 3 in first session, 3 in second session,and 8 in the last session. Here, the user consumed 14 counts in total, though only 10were allowed.

If the user renews the license, the additional number of counts consumed (4 in theabove case) will be deducted in the next licenses term. For example, on license renewalwith 10 counts, the previously consumed 4 counts will be deducted and the user willhave 6 effective counts remaining. This way the actual license usage is taken intoaccount eventually, though not always.

Please note that usage count is updated only after usage has been synched with CloudConnect. Let us say, you specified usageCountMultiplier as 4. The number of countsconsumed will remain incremented by 1 until the usage is synched with Cloud Connect.After usage syncs, the number of counts consumed will be incremented by 4.

Interfaces

3.13.1. The Attributes Class (Java) 128

3.13.2. The Attributes Class (.NET) 129

3.13.3. scr_Attributes_t (C) 129



3.13.1. The Attributes Class (Java)

Description

This class is a set of internal classes and objects that define custom attributes. You can use customattributes to track and monetize the feature usage by customers. For example, you can specify howmuch bandwidth your customers are consuming, howmuch data is being stored or downloaded, andhowmany times a feature is being used.

The custom attributes are provided while calling a run-time API. The subsequent sections describecontents of the Attributes class for the various run-time APIs.

In this release, the Attributes class provides internal classes containing custom attributes forthe logout API only.

logout API Related Attributes and Public Members

This section describes the internal classes and public members provided by the Attributes class for thelogout API.

Public Members

You can use the public members to set or get custom attributes. The public member available is:

n logOutAttributes: An object of the LogoutAttributes internal class. It is used to provide cus-tom attributes corresponding to the logout API.

Custom Attributes

You can provide the usageCountMultiplier custom attribute with the logout API.

Internal Class(es)

n LogoutAttributes: An internal class of Attributes class that contains custom attributes for thelogout API.

The following tables list the functions of the LogoutAttributes class.


getUsageCountMultiplier

public intgetUsageCountMultiplier()

Gets the value ofusageCountMultiplier

None Value ofusagecountmultiplier

setUsageCountMultiplier

public voidsetUsageCountMultiplier(int value)

Sets the value ofusageCountMultiplier

Value - Value of usagecount multiplier

None

Related Topics:

logout

3.13.2. The Attributes Class (.NET)

Description

This class is a set of internal classes and objects that define custom attributes. You can use customattributes to track and monetize the feature usage by customers. For example, you can specify howmuch bandwidth your customers are consuming, howmuch data is being stored or downloaded, andhowmany times a feature is being used.

The custom attributes are provided while calling a run-time API. The subsequent sections describecontents of the Attributes class for the various run-time APIs.

In this release, the Attributes class provides internal classes containing custom attributes forthe logout API only.

logout API Related Attributes and Public Members

This section describes the internal classes and public members provided by the Attributes class for thelogout API.

Public Members

You can use the public members to set or get custom attributes. The public member available is:

n logOutAttributes: An object of the LogoutAttributes internal class. It is used to provide cus-tom attributes corresponding to the logout API.

Custom Attributes


Internal Class(es)

n LogoutAttributes: An internal class of Attributes class that contains custom attributes for thelogout API.

The following tables list the functions of the LogoutAttributes class.


UsageCountMultiplier

public int UsageCountMultiplier Gets and sets the value of usageCountMultiplier

Related Topics:

logout

3.13.3. scr_Attributes_t (C)

This structure is a set of internal structures and objects that define custom attributes. You can usecustom attributes to track and monetize the feature usage by customers. For example, you canspecify howmuch bandwidth your customers are consuming, howmuch data is being stored ordownloaded, and howmany times a feature is being used.



The custom attributes are provided while calling a run-time API. The subsequent sections describecontents of the Attributes structure for the various run-time APIs.

In this release, the Attributes structure provides an internal structure containing customattributes for the scr_logout (C) API only.

logout API Related Attributes


3.14. LoginOptionalParamContains optional parameters for the login API, such as Capacity and Vendor Data.

Interfaces

3.14.1. The LoginOptionalParam Class (Java) 131

3.14.2. The LoginOptionalParam Class (.NET) 131

3.14.3. scr_LoginOptionalParam_t (C) 132

3.14.1. The LoginOptionalParam Class (Java)

This class contains optional parameters to be passed to the login API.

Functions

This section describes the public functions of the LoginOptionalParam class:


setVendorData

public voidsetVendorData(StringvendorData)

Stores thevendor-specificinformation

vendorData - Vendor information or the remarks tostore in usage record (if a feature is authorizedsuccessfully).This parameter can be used hold any value basedon which you want categorize usage. Based on thevalue specified here, you can generate an EMSreport, 'Vendor Info Usage Report'.For example, you can store name of a region in thisparameter, and then you can use the 'Vendor InfoUsage Report' for region-wise filtering of usage data.For report details, please refer to EMS User's Guide.The size is limited to 255 bytes.

None

setCookie

public voidsetCookie(Stringcookie)

Stores theauthenticationcookie

setCookie - Stores the cookie returned by thegetIdentity API.

This parameter is applicable only when on-premise feature level licensing is used withauthentication.

None

setCapacity

public voidsetCapacity(intcapacity)

Stores thecapacity for afeature.

setCapacity - A vendor-specific value thatrepresents the load on a feature during a particularlogin session. It is used for computing peak capacityof a feature.For more information, refer to section AboutCapacity.

None

3.14.2. The LoginOptionalParam Class (.NET)

This class contains optional parameters to be passed to the login API.

Functions

This section describes the public functions of the LoginOptionalParam class:

3.14. LoginOptionalParam 131



VendorData

public StringVendorData

The vendor-specific information to be stored in a usage record (if a feature isauthorized successfully).This parameter can be used hold any value based on which you wantcategorize usage. Based on the value specified here, you can generate anEMS report, 'Vendor Info Usage Report'.For example, you can store name of a region in this parameter, and thenyou can use the 'Vendor Info Usage Report' for region-wise filtering of usagedata.For report details, please refer to EMS User's Guide.The size is limited to 255 bytes.

public String Cookie Stores the cookie returned by the getIdentity API.

This parameter is applicable only when on-premise feature levellicensing is used with authentication.

public int Capacity Stores the capacity value for a feature.A vendor-specific value that represents the load on a feature during aparticular login session. It is used for computing peak capacity of a feature.For more information, refer to section About Capacity.

3.14.3. scr_LoginOptionalParam_t (C)

This structure contains optional parameters for the scr_login (C) API.

Syntax

typedef struct scr_LoginOptionalParam{

char *VendorData;

char *cookie;

int Capacity;

} scr_LoginOptionalParam_t;

Members


VendorData char* String containing the vendor-specific remarks to be stored inusage record (if a feature is authorized successfully).This parameter can be used hold any value based on which youwant categorize usage. Based on the value specified here, you cangenerate an EMS report, 'Vendor Info Usage Report'.For example, you can store name of a region in this parameter,and then you can use the 'Vendor Info Usage Report' for region-wise filtering of usage data.For report details, please refer to EMS User's Guide.


The size is limited to 255 bytes.

cookie char* Stores the cookie returned by the scr_getIdentity(C) API.

This parameter is applicable only when on-premise featurelevel licensing is used with authentication.

Capacity int Stores the capacity value for a feature.A vendor-specific value that represents the load on a featureduring a particular login session. It is used for computing peakcapacity of a feature.For more information, refer to section About Capacity.

3.15. LoginResponseStores the response of the login API.

Interfaces

3.15.1. The LoginResponse Class (Java) 134

3.15.2. The LoginResponse Class (.NET) 135

3.15.3. scr_LoginResponse_t (C) 136



3.15.1. The LoginResponse Class (Java)

This class stores the response of the login API.

Functions

This section describes the public functions of the LoginResponse class:


getSessionHandle

public String getSessionHandle() Gets the session handlereturned by the login API.This is used at the time oflogout.

None Session handle

public int getIsCachedSuccess() This flag value specifies if theauthorization is done in theconnected or disconnectedmode.

n 0- Connected mode(when Run-time isconnected to DirectoryServices and CloudConnect)

n 1- Disconnected mode(when Run-time is notconnected to DirectoryServices and CloudConnect)

A connection is required to syncusage and licenses.

None Integercontaining theflag value

public intgetIsMaxUsageReached()

This flag value specifies if theusage log for the authorizedfeature is accumulated or not.

n 0 – Usage log isaccumulated

n 1- Usage log is notaccumulated and allsubsequent usage detailsare lost. To avoid usagedata loss, the applicationshould connect back.

Run-time accumulatesthe authorization dataduring the disconnected



mode. If due tocontinuousdisconnection, the datasize reaches a specifiedlimit, Run-time stopsaccumulating the datafurther till the data ispushed to SentinelCloud Connect.

The getIsCachedSuccess() and getIsMaxUsageReached() functions are applicable only for on-premise applications.

3.15.2. The LoginResponse Class (.NET)

This class stores the response of the login API.

Functions



SessionHandle

public String SessionHandle Gets the session handle returned by the loginAPI.This is used at the time of logout.

isCachedSuccess

public int isCachedSuccess Specifies if the authorization is done in theconnected or disconnected mode.

n 0- Connected mode (when Run-time isconnected to Directory Services andCloud Connect)

n 1- Disconnected mode (when Run-time isnot connected to Directory Services andCloud Connect)

A connection is required to sync usage andlicenses.

isMaxUsageReached

public int isMaxUsageReached Specifies if the usage log for the authorizedfeature is accumulated or not.

n 0 – Usage log is accumulatedn 1- Usage log is not accumulated and all

subsequent usage details are lost. To




avoid usage data loss, the applicationshould connect back.

Run-time accumulates theauthorization data during thedisconnected mode. If due tocontinuous disconnection, the data sizereaches a specified limit, Run-time stopsaccumulating the data further till thedata is pushed to Sentinel CloudConnect.

The isCachedSuccess and isMaxUsageReached properties are applicable only for on-premiseapplications.

3.15.3. scr_LoginResponse_t (C)

This structure stores the response of the scr_login (C) API.

Syntax

typedef struct scr_LoginResponse{

char *SessionHandle;

int isCachedSuccess;

int isMaxUsageReached;

} scr_LoginResponse_t;

Members


SessionHandle char * The session handle returned by the login API. This is used at thetime of logout.

isCachedSuccess int Specifies if the authorization is done in the connected ordisconnected mode.

n 0- Connected mode (when Run-time is connected toDirectory Services and Cloud Connect)

n 1- Disconnected mode (when Run-time is not connectedto Directory Services and Cloud Connect)

A connection is required to sync usage and licenses.

This function is applicable only for on-premiseapplications.

isMaxUsageReached int Specifies if the usage log for the authorized feature isaccumulated or not.

n 0 – Usage log is accumulated


n 1- Usage log is not accumulated and all subsequentusage details are lost. To avoid usage data loss, theapplication should connect back.

Run-time accumulates the authorization data during thedisconnected mode. If due to continuousdisconnection, the data size reaches a specified limit,Run-time stops accumulating the data further till thedata is pushed to Sentinel Cloud Connect.

3.16. LogoutOptionalParamContains the optional parameters for the logout API.

Interfaces

3.16.1. The LogoutOptionalParam Class (Java) 138

3.16.2. The LogoutOptionalParam Class (.NET) 138

3.16.3. scr_LogoutOptionalParam_t (C) 138

3.16. LogoutOptionalParam 137


3.16.1. The LogoutOptionalParam Class (Java)

This class contains the optional parameters for the logout API.

Functions

This section describes the public functions of the LogoutOptionalParam class:


setAttributes

public voidsetAttributes(Attributes attributes)

Sets the customattributes you wantto pass to thelogout API.

attributes -Object of the Attributes class,containing custom usageattributes for the logout API.See: Attributes

If this parameter is null,the default usage isconsidered as 1.

None

3.16.2. The LogoutOptionalParam Class (.NET)

This class contains the optional parameters for the logout API.

Functions

This section describes the public functions of the LogoutOptionalParam class:

Properties Description Parameters Returns

Attributes

public AttributesAttribute

Sets the customattributes you wantto pass to thelogout API.

Attribute -Object of the Attributes class,containing custom usageattributes for the logout API.See: Attributes

If this parameter is null,the default usage isconsidered as 1.

None

3.16.3. scr_LogoutOptionalParam_t (C)

This structure contains the optional parameters for the scr_logout (C) API.

Syntax

typedef struct scr_LogoutOptionalParam{

scr_Attributes_t Attribute;

} scr_LogoutOptionalParam_t;

Members


Attribute scr_Attributes_t

Structure of the type scr_Attributes_t (C), containing customusage attributes for the logout API.See: Attributes

If this parameter is null, the default usage is considered as1.

3.17. LogoutResponseStores the response of the logout API.

Interfaces

3.17.1. The LogoutResponse Class (Java) 140

3.17.2. The LogoutResponse Class (.NET) 140

3.17.3. scr_LogoutResponse_t (C) 141

3.17. LogoutResponse 139


3.17.1. The LogoutResponse Class (Java)

This class stores the response of the logout API.

Functions



getIsMaxUsageReached

public intgetIsMaxUsageReached()

This flag value specifies if theusage log for the authorizedfeature is accumulated or not.

n 0 – Usage log isaccumulated

n 1- Usage log is notaccumulated

Run-time accumulatesthe authorization dataduring the disconnectedmode. If due tocontinuousdisconnection, the datasize reaches a specifiedlimit, Run-time stopsaccumulating the datafurther till the data ispushed to SentinelCloud Connect.


The getIsMaxUsageReached() function is applicable only for on-premise applications.

3.17.2. The LogoutResponse Class (.NET)

This class stores the response of the logout API.

Functions



isMaxUsageReached

public int isMaxUsageReached Specifies if the usage log for the authorizedfeature is accumulated or not.

n 0 – Usage log is accumulated


n 1- Usage log is not accumulated

Run-time accumulates theauthorization data during thedisconnected mode. If due tocontinuous disconnection, the data sizereaches a specified limit, Run-time stopsaccumulating the data further till thedata is pushed to Sentinel CloudConnect.

The isMaxUsageReached property is applicable only for on-premise applications.

3.17.3. scr_LogoutResponse_t (C)

This structure stores the response of the scr_logout (C) API.

Syntax

typedef struct scr_LogoutResponse{

int isMaxUsageReached;

} scr_LogoutResponse_t;

Members


isMaxUsageReached int Specifies if the usage log for the authorized feature isaccumulated or not.

n 0 – Usage log is accumulatedn 1- Usage log is not accumulated

Run-time accumulates the authorization data during thedisconnected mode. If due to continuousdisconnection, the data size reaches a specified limit,Run-time stops accumulating the data further till thedata is pushed to Sentinel Cloud Connect.

3.18. RefreshSessionOptionalParamReserved for future use. Currently only the dummy classes/structure are provided for the supportedlanguages. In future, these will be used to hold the optional parameters for the refreshSession API.

Interfaces

3.18.1. The RefreshSessionOptionalParam Class (Java) 142

3.18.2. The RefreshSessionOptionalParam Class (.Net) 142

3.18. RefreshSessionOptionalParam 141


3.18.3. scr_RefreshSessionOptionalParam_t (C) 142

3.18.1. The RefreshSessionOptionalParam Class (Java)

Reserved for future use. In future, this class will be used to hold the optional parameters for therefreshSession API.

3.18.2. The RefreshSessionOptionalParam Class (.Net)

Reserved for future use. In future, this class will be used to hold the optional parameters for therefreshSession API.

3.18.3. scr_RefreshSessionOptionalParam_t (C)

Description

Reserved for future use. In future, this structure will be used to hold the optional parameters for therefreshSession API.

3.19. RefreshSessionResponseStores the response of the refreshSession API.

Interfaces

3.19.1. The RefreshSessionResponse Class (Java) 143

3.19.2. The RefreshSessionResponse Class (.Net) 143

3.19.3. scr_RefreshSessionResponse_t (C) 143

3.19.1. The RefreshSessionResponse Class (Java)

This class stores the response of the refreshSession API.

Functions



getSessionHandle

public String getSessionHandle() Gets the session handlereturned by the login API.

None Session handle

3.19.2. The RefreshSessionResponse Class (.Net)

This class stores the response of the refreshSession API.

Functions



SessionHandle

public String SessionHandle Gets or sets the session handle returned by thelogin API.

3.19.3. scr_RefreshSessionResponse_t (C)

Description

This structure stores the response of the scr_refreshSession (C) API.

Syntax

typedef struct scr_

RefreshSessionResponse{

char *sessionHandle;

} scr_RefreshSessionResponse_t;

Members


sessionHandle char * The session handle returned by the login API.

3.19. RefreshSessionResponse 143


3.20. GetIdentityOptionalParamReserved for future use. Currently only the dummy classes/structure are provided for the supportedlanguages. In future, these will be used to hold the optional parameters for the getIdentity API.

Interfaces

3.20.1. The GetIdentityOptionalParam Class (Java) 145

3.20.2. The GetIdentityOptionalParam Class (.NET) 145

3.20.3. scr_GetIdentityOptionalParam_t (C) 145

3.20.1. The GetIdentityOptionalParam Class (Java)

Reserved for future use. In future, this class will be used to hold the optional parameters for thegetIdentity API.

3.20.2. The GetIdentityOptionalParam Class (.NET)

Reserved for future use. In future, this class will be used to hold the optional parameters for thegetIdentity API.

3.20.3. scr_GetIdentityOptionalParam_t (C)

This structure is reserved for future use. Currently a dummy structure is provided, which in future willbe used to hold the optional parameters for the scr_getIdentity API.

3.21. GetIdentityResponseStores the response of the getIdentity API.

Interfaces

3.21.1. The GetIdentityResponse Class (Java) 146

3.21.2. The GetIdentityResponse Class (.NET) 146

3.21.3. scr_GetIdentityResponse_t (C) 147

3.21. GetIdentityResponse 145


3.21.1. The GetIdentityResponse Class (Java)

This class stores the response of the getIdentity API.

Functions



getCookieId

public String getCookieId() Cookie returned by thegetIdentity API. The cookieremains valid for a specificduration as defined by the ISV.

None Cookie

getUser

public String getUser() User ID of the authenticateduser. This value is passed to thelogin API.

None User ID

getCustomer

public String getCustomer() Customer reference ID mappedto the authenticated user. Thisvalue is passed to the login API.

None Customerreference ID

getAuthPayload

public String getAuthPayload() Contains authPayLoad string asspecified by ISV in theauthentication database. It isan optional value and will bereturned only if available indatabase.

None authPayLoadstring

3.21.2. The GetIdentityResponse Class (.NET)

This class stores the response of the getIdentity API.

Functions



CookieId

public String CookieId Cookie returned by the getIdentity API. The cookie remains valid for aspecific duration as defined by the ISV.

User

public String User User ID of the authenticated user. This value is passed to the loginAPI.


Customer

public String Customer Customer reference ID mapped to the authenticated user. This valueis passed to the login API.

AuthPayLoad

public String AuthPayLoad Contains authPayLoad string as specified by ISV in the authenticationdatabase. It is an optional value and will be returned only if availablein database.

3.21.3. scr_GetIdentityResponse_t (C)

This structure stores the response of the scr_getIdentity(C) API.

Syntax

typedef struct scr_GetIdentityResponse{

char * CookieId;

char * User;

char * Customer;

char * AuthPayLoad;

}scr_GetIdentityResponse_t;

Members


CookieId char* Cookie returned by the scr_getIdentity API.

The cookie remains valid for a specific duration as definedby the ISV.

User char* User ID of the authenticated user. This value is passed to the scr_login API.

Customer char* Customer reference ID mapped to the authenticated user. Thisvalue is passed to the scr_login API.

AuthPayLoad char* Contains authPayLoad string as specified by ISV in theauthentication database.

It is an optional value and will be returned only if availablein database.

3.22. TransferOptionalParamContains optional parameters for the transfer API.

Interfaces

3.22.1. The TransferOptionalParam Class (Java) 148



3.22.2. The TransferOptionalParam Class (.NET) 149

3.22.3. scr_TransferOptionalParam_t 150

3.22.1. The TransferOptionalParam Class (Java)

This class contains optional parameters to be passed to the transfer API.

Functions



setInterval

public void setInterval(int interval)

Specifies the detachinterval.

interval -Maximum duration, in hour(s), for which the license can bedetached.You must set this parameter whilecalling the transfer API with the DETACH(1) action.A value of -1 is also allowed.

See section Detach Interval forinformation on how the actualdetach interval is determined.

None

setCookie

public void setCookie(String cookie)

Stores theauthenticationcookie.

cookie -Authentication cookie returned by thegetIdentity API.

This parameter is applicable onlywhen on-premise feature levellicensing is used withauthentication.

None

currentLicenseState

public voidsetCurrentLicenseState(StringcurrentLicenseState)

The current state oflicenses on theisolated machines.This parameter isapplicable only for on-premise entitlementscreated with featurecaching mode asentitlement level.

currentLicenseState - String containinglicense state as fetched by using thegetInfo API. This parameter is passedwith the transfer action REMOTE_DETACH.

None

UpdatedLicenseState

public void The snapshot of the UpdatedLicenseState - String containing None


setUpdatedLicenseState(StringUpdatedLicenseState)

licenses fetched fromCloud Connect for theisolated machine.This parameter isapplicable only for on-premise entitlementscreated with featurecaching mode asentitlement level.

the updated license state as fetchedfrom Cloud Connect by using thetransfer API. This parameter is passedwith the transfer action APPLY_REMOTE_LICENSE.

3.22.2. The TransferOptionalParam Class (.NET)

This class contains optional parameters to be passed to the transfer API.

Functions



Cookie

public String Cookie Authentication cookie returned by the getIdentity API.

This parameter is applicable only when on-premisefeature level licensing is used with authentication.

Interval

public int Interval Maximum duration, in hour(s), for which the license can bedetached.You must set this parameter while calling the transfer API withthe DETACH(1) action.A value of -1 is also allowed.

See section Detach Interval for information on how theactual detach interval is determined.

CurrentLicenseState

public StringCurrentLicenseState

The current state of licenses on the isolated machines.This parameter is applicable only for on-premise entitlementscreated with feature caching mode as entitlement level.

UpdatedLicenseState

public StringUpdatedLicenseState

The snapshot of the licenses fetched from Cloud Connect forthe isolated machine.This parameter is applicable only for on-premise entitlementscreated with feature caching mode as entitlement level.



3.22.3. scr_TransferOptionalParam_t

This structure contains optional parameters for the scr_transfer (C) API.

Syntax

typedef struct scr_

TransferOptionalParam{

char *Cookie;

char *CurrentLicenseState;

char *UpdatedLicenseState;

unsigned int Interval;

} scr_TransferOptionalParam_t;

Members


Cookie char* The authentication cookie returned by the scr_getIdentity API.

This parameter is applicable only when on-premisefeature level licensing is used with authentication.

CurrentLicenseState char* The current state of licenses on the isolated machines.This parameter is applicable only for on-premise entitlementscreated with feature caching mode as entitlement level.

UpdatedLicenseState char* The snapshot of the licenses fetched from Cloud Connect forthe isolated machine.This parameter is applicable only for on-premise entitlementscreated with feature caching mode as entitlement level.

Interval unsigned int Maximum duration, in hour(s), for which the license can bedetached.You must set this parameter while calling the transfer API withthe DETACH(1) action.A value of -1 is also allowed.

See section Detach Interval for information on how theactual detach interval is determined.

3.23. TransferResponseThis class is used to store the response of the transfer API.

Interfaces

3.23.1. The TransferResponse Class (Java) 151

3.23.2. The TransferResponse Class (.NET) 151

3.23.3. scr_TransferResponse_t (C) 151

3.23.1. The TransferResponse Class (Java)

This class is used to store the response of the transfer API.

Functions



getUpdatedLicenseState

public StringgetUpdatedLicenseState()

Fetches the updatedlicense state fromCloud Connect.

None Updatedstate oflicense

3.23.2. The TransferResponse Class (.NET)

This class is used to store the response of the transfer API.

Functions



UpdatedLicenseState

public StringUpdatedLicenseState

Updated license state as fetched from Cloud Connect.

3.23.3. scr_TransferResponse_t (C)

This structure contains optional parameters for the scr_transfer (C) API.

Syntax

typedef struct scr_TransferResponse{

char *UpdatedLicenseState;

} scr_TransferResponse_t;

Members


UpdatedLicenseState char* Stores the license update.

3.24. FeaturesContains list of features to detach or return by using the transfer API.

3.24. Features 151


Interfaces

scr_Features_t (C)

For Java and .NET, the feature list is stored as an array of objects of the SaaSFeatureNodeclass.

3.24.1. scr_Features_t (C)

This structure contains features detached or returned by the scr_transfer API.

Syntax

typedef struct scr_Feature{

scr_FeatureNode_t *FeatureNode;

int NumElements;

} scr_Features_t;

Members


FeatureNode scr_FeatureNode_t

Structure of the type scr_FeatureNode_t (C) containing listof features to detach or return.

NumElements int Number of features in feature list.

3.25. AcquireClientOptionalParamReserved for future use. Currently only the dummy classes/structure are provided for the supportedlanguages. In future, these will be used to hold the optional parameters for the acquireLicenseClientAPI.

Interfaces

3.25.1. The AcquireClientOptionalParam Class (Java) 153

3.25.2. The AcquireClientOptionalParam Class (.Net) 153

3.25.3. scr_AcquireClientOptionalParam_t (C) 153

3.25.1. The AcquireClientOptionalParam Class (Java)

Reserved for future use. In future, this class will be used to hold the optional parameters for theacquireLicenseClient API.

3.25.2. The AcquireClientOptionalParam Class (.Net)

Reserved for future use. In future, this class will be used to hold the optional parameters for theacquireLicenseClient API.

3.25.3. scr_AcquireClientOptionalParam_t (C)

This structure is reserved for future use. Currently a dummy structure is provided, which in future willbe used to hold the optional parameters for the acquireLicenseClient API.

3.26. The AcquireClientResponse ClassReserved for future use. Currently only the dummy classes/structure are provided for the supportedlanguages. In future, these will be used to hold the response of the acquireLicenseClient API.

Interfaces

3.26.1. The AcquireClientResponse Class (Java) 154

3.26.2. The AcquireClientResponse Class (.Net) 154

3.26.3. scr_AcquireClientResponse_t (C) 154

3.26. The AcquireClientResponse Class 153


3.26.1. The AcquireClientResponse Class (Java)

Reserved for future use. In future, this class will be used to hold the response of theacquireLicenseClient API.

3.26.2. The AcquireClientResponse Class (.Net)

Reserved for future use. In future, this class will be used to hold the response of theacquireLicenseClient API.

3.26.3. scr_AcquireClientResponse_t (C)

This structure is reserved for future use. Currently a dummy structure is provided, which in future willbe used to hold the response of the acquireLicenseClient API.

3.27. ConfigurationContains configuration properties to be provided to Run-time in the acquireLicenseClient API call. Theconfiguration properties aremanaged as key/value pairs.

Configuration Properties

The Configuration class/structure allows you to provide the following properties in theacquireLicenseClient API call:

PropertyDataType

Description

InMemoryUsageCount String Set this property to 0 if you want to disable the usage cache.By default, usage cache is enabled and a small number of recordsare kept in cache before they are pushed to a persistent store.When usage cache is disabled, usage records are written directly topersistent store (physical disk).

n Valid Value is 0, which means that the usage cache isdisabled.

n For a value other than 0, an error is thrown.n It is an optional property, and applicable only for on-

premise deployments.

These properties are additional to those defined in the Client Configuration File.

Interfaces

3.27.1. The Configuration Class (Java) 155

3.27.2. The Configuration Class (.NET) 156

3.27.3. scr_Configuration_t (C) 158

3.27.1. The Configuration Class (Java)

Contains configuration properties to be passed to Run-time in the acquireLicenseClient API call. Theconfiguration properties aremanaged as key/value pairs.

Functions

This section describes the public functions of the Configuration class:

Name\Syntax

DescriptionParameters

Returns

Configuration

publicConfiguration()

After using this constructor, the application must call theset API before providing the configuration object to theCloud Run-time API.

None None

setConfig

public voidsetConfig(Propertiesconfig)

Loads the configuration from properties.Properties class represent the name/value pair. In eachpair, the key and value are both String values.http://docs.oracle.com/javase/tutorial/essential/environment/properties.html

Configurationobject

None

getConfig

publicPropertiesgetConfig()

Returns the configuration loaded by setConfig() call. NoneConfigurationobject

set

public voidset(Stringname,Stringvalue)throwsLicenseException

Sets the configuration item name and its value. Configurationnameandvalue

None

get

publicString get(Stringname)

Gets the configuration item value for given name. Configurationname

None

remove

public voidremove(String

Removes the configuration item for given name. Configurationname

None


http://docs.oracle.com/javase/tutorial/essential/environment/properties.html

http://docs.oracle.com/javase/tutorial/essential/environment/properties.html


Name\Syntax

DescriptionParameters

Returns

name)

length

public intlength()

Returns the number of elements in this list. None Numberof listelements

reset

public voidreset()

Reset the configuration list. Resetting a configuration listdiscard all of its elements.

None None

next

publicbooleannext()

Returns the next item from configuration list. Returnfalse if no item exists.

None Nextconfiguration item

getConfigName

publicStringgetConfigName()

Returns the configuration item name. This is used whileiterating using next() call.

None Configurationname

getConfigValue

publicStringgetConfigValue()

Returns the configuration item value. This is used whileiterating using next() call.

None Configurationvalue

Related Topics:

getInfo

3.27.2. The Configuration Class (.NET)


Functions

This section describes the public functions of the Configuration class:


Configuration

public Configuration() After usingthisconstructor,theapplication

None None


must call theset APIbeforeproviding theconfigurationobject to theCloud Run-time API.

set

public void set(String name, Stringvalue)

Sets theconfigurationitem nameand its value.

Configurationname andvalue

None

get

public String get(String name) Gets theconfigurationitem valuefor givenname.

Configurationname

None

remove

public void remove(String name) Removes theconfigurationitem forgiven name.

Configurationname

None

length

public int length() Returns thenumber ofelements inthis list.

None Number of list elements

reset

public void reset() Reset theconfigurationlist. Resettingaconfigurationlist discard allof itselements.

None None

next

public boolean next() Returns thenext itemfromconfiguration

None Next configuration item




list. Returnfalse if noitem exists.

Name

public String Name() Returns theconfigurationitem name.This is usedwhileiteratingusing next()call.

None Configuration name

Value

public String Value() Returns theconfigurationitem value.This is usedwhileiteratingusing next()call.

None Configuration value

Related Topics:

getInfo

3.27.3. scr_Configuration_t (C)


Syntax

typedef struct scr_Configuration {

char *Name;

char *Value;

struct scr_Config *Next;

} scr_Configuration_t;

Members


Name char* String containing the configuration name.

Value char* String containing the configuration value.

Next scr_Config Next element of scr_Configuration_t.

3.28. LicenseExceptionUsed for exception processing.

The LicenseException class helps to define and retrieve error codes for the exceptions that occurduring the functioning of Cloud Run-time. Retrieving the error code allows you to identify the cause ofexception and handle it appropriately.

Interfaces

3.28.1. The LicenseException Class (Java) 160

3.28.2. The LicenseException Class (.NET) 161



LicenseException does not exist in the C interface of Cloud Run-time.

3.28.1. The LicenseException Class (Java)

This class is used for exception processing. This class helps to define and retrieve error codes for thevarious exceptions, which occur during the functioning of Cloud Run-time. Retrieving the error codeallows you to identify the cause of exception and handle it appropriately.

Constructors

The following table lists the constructors of the LicenseException class:


Default publicLicenseException(String strMessage)

Initializes errormessage to besent to the user.

strMessage - String containingerror information to be sent tothe caller.

Constructorwith arguments

publicLicenseException(String strMessage,String[]arrArguments

Contains errormessages alongwith argumentinformation.

n strMessage - Stringcontaining errorinformation to be sentto the caller.

n arrArguments - Stringcontaining extraarguments informationto be included inexception description.

Functions

This section describes the public functions of the LicenseException class:


setErrorCodepublic voidsetErrorCode(intiErrorCode)

Defines an error code iErrorCode - Value oferror code to bedefined

None

getErrorCodepublic intgetErrorCode()

Retrieves the error code. Thishelps to analyze the cause ofexception.

None Error codeof theexception

getMessagepublic StringgetMessage()

Retrieves a string containingdetails about the exception.

None String

3.28.2. The LicenseException Class (.NET)

This class is used for exception processing. This class helps to define and retrieve error codes for thevarious exceptions, which occur during the functioning of Cloud Run-time. Retrieving the error codeallows you to identify the cause of exception and handle it appropriately.

Constructors

The following table lists the constructors of the LicenseException class:


Default publicLicenseException(StringstrMessage)

Initializes error messageto be sent to the user.

strMessage - Stringcontaining errorinformation to be sentto the caller.

Constructorwith arguments

publicLicenseException(StringstrMessage,ExceptioninnerException)

Contains error messagesalong with a reference tothe inner exception (thecause behind the errorthrown).

n strMessage -String containingerror informationto be sent to thecaller.

n innerException -Reference to theinner exception.

Functions

This section describes the public functions of the LicenseException class:


errorCodepublic interrorCode

Gets or sets the error code. This helps to analyze the cause ofexception.


Chapter 4:Enumerations (C)

This section explains the following enumerations included in C interfaces of Cloud Run-time.

4.1. scr_Count_t (C) 164

4.2. scr_FormatType_t (C) 164

4.3. scr_Action_t 165

4

164 Chapter 4: Enumerations (C)

4.1. scr_Count_t (C)Type of concurrency.

4.1.1. Members

Member Description

STATION Concurrency due to number ofmachines.

LOGIN Concurrency due to number of loginsessions.

IDENTITY Concurrency due to number of users.

Currently, for Cloud applications, only LOGIN and IDENTITY are supported. For On-premiseapplications deployed with Entitlement Level feature caching mode, only LOGIN is supported.For On-premise applications deployed with Feature Level feature caching mode, only STATIONis supported.

4.2. scr_FormatType_t (C)Specifies the level of detail you want to obtain from the scr_getInfo (C) API, and how to display theobtained information.

4.2.1. Members






n In the case of Cloud deployment, the featureinformation can include licensemodel, start date,end date, concurrency, prepaid count and otherlicense attributes.






4.3. scr_Action_tSpecifies the function performed by the scr_transfer (C) API .

4.3.1. Members

Member Description

DETACH Detaches the license. Detaches the license. In this case, youmust specify a detach interval in the scr_TransferOptionalParam_t structure.

CANCEL_DETACH

Returns the license to Cloud Connect. It also releases thestation in case of entitlement level.

SYNC_USAGE Syncs all usage logs stored on a machine to Cloud Connect.With this value, the scr_transfer (C) API call acts as a blockingcall, as no other API can execute in the same thread until allusage is pushed to Cloud Connect.

This is optional. Use this option only when you donot want to wait for periodic usage transfer and wantto send the usage instantly.

REMOTE_DETACH

Detaches a license for an isolated on-premisemachine.

APPLY_REMOTE_LICENSE

Applies the license update to an isolated on-premisemachine.

4.3. scr_Action_t 165

Chapter 5:Sample Code of Cloud Run-time APIs

This section contains snippets to illustrate how to implement Cloud Run-time APIs in your sourcecode.

These sample codes aremeant for demonstration purpose only. In the production setup, youwill need to modify the ISV application according to business requirements.

5.1. Sample Code - acquireLicenseClient 168

5.2. Sample Code - getIdentity 171

5.3. Sample Code - transfer 175

5.4. Sample Code - getInfo 179

5.5. Sample Code - login 193

5.6. Sample Code - refreshSession 198

5.7. Sample Code - logout 201

5.8. Sample Code - releaseLicenseClient 205

5

168 Chapter 5: Sample Code of Cloud Run-time APIs

5.1. Sample Code - acquireLicenseClientYou can call the acquireLicenseClient API at the time of application initialization.

5.1.1. Sample Code - acquireLicenseClient (Java) 169

5.1.2. Sample Code - acquireLicenseClient (.NET) 169

5.1.3. Sample Code - scr_acquireLicenseClient (C) 170

5.1.1. Sample Code - acquireLicenseClient (Java)

The ‘init’ function of web services is one of the possible places where you can insert theacquireLicenseClient API call. You can store the Cloud Run-time instance returned by this API in a staticCloud Run-time variable.

Following sample shows how to initialize Cloud Run-time in the ‘init’ function:

import javax.servlet.ServletConfig;import javax.servlet.ServletException;import javax.servlet.http.HttpServlet;

import com.sfnt.saas.common.Configuration;

class SampleServlet extends HttpServlet{

/* object containing license client instance */private static LicenseRuntime licRuntime = null;

/* API to initialize servlet */public void init(ServletConfig config) throws ServletException{

Configuration configuration = null;AcquireClientOptionalParam acquireClientOptionalParam = null;AcquireClientResponse acquireClientResponse = null;try{

configuration = new Configuration();configuration.set("InMemoryUsageCount", "0");

/* store license client instance while initializing application */licRuntime = LicenseRuntime.acquireLicenseClient(configuration, acquireCli-

entOptionalParam,acquireClientResponse);

} catch (LicenseException e){

e.printStackTrace();}

}}

5.1.2. Sample Code - acquireLicenseClient (.NET)

The ‘init’ function of web services is one of the possible places where you can insert theacquireLicenseClient API call. Store the Cloud Run-time instance returned by this API in a static CloudRun-time variable.

Following sample shows how to initialize Cloud Run-time in the ‘init’ function:

import javax.servlet.ServletConfig;import javax.servlet.ServletException;import javax.servlet.http.HttpServlet;

import com.sfnt.saas.common.Configuration;

5.1. Sample Code - acquireLicenseClient 169


class SampleServlet extends HttpServlet{

/* object containing license client instance */private static LicenseRuntime licRuntime = null;

/* API to initialize servlet */public void init(ServletConfig config) throws ServletException{

Configuration configuration = null;AcquireClientOptionalParam acquireClientOptionalParam = null;AcquireClientResponse acquireClientResponse = null;try{

configuration = new Configuration();configuration.set("InMemoryUsageCount", "0");

/* store license client instance while initializing application */licRuntime = LicenseRuntime.acquireLicenseClient(configuration, acquireCli-

entOptionalParam,acquireClientResponse);

} catch (LicenseException e){

e.printStackTrace();}

}}

5.1.3. Sample Code - scr_acquireLicenseClient (C)

Following sample shows how to call the acquireLicenseClient API for initializing Sentinel Cloud Run-time library:

void applicationInit(){

int returnCode = -1;scr_Configuration_t config = {0};scr_AcquireClientOptionalParam_t *acquireClientOptParam = NULL;scr_AcquireClientResponse_t *acquireClientResponse = NULL;

/* Set configuration property, if any */config = { "InMemoryUsageCount", //key

"0", //valueNULL //next

};

/* initializes license runtime */returnCode = scr_acquireLicenseClient(&config, acquireClientOptParam, &ac-

quireClientResponse);if(returnCode != RT_SUCCESS){

printf("\n Error in scr_acquireLicenseClient # %d", returnCode);}else{

printf("\n scr_acquireLicenseClient is successful.");}

}

5.2. Sample Code - getIdentityYou can call the getIdentity API after acquireLicenseClient and before login/transfer API calls.

n This API is available only for on-premise feature level licensing.

n To use this API, you need to integrate an authentication system with Sentinel Cloud. Ifthe authentication system is not available, you can implement on-premise featurelevel licensing, but without using authentication. For information on how to integratean authentication system, please contact SafeNet.

5.2.1. Sample Code - getIdentity (Java) 172

5.2.2. Sample Code - getIdentity (.NET) 172

5.2.3. Sample Code - getIdentity (C) 173



5.2.1. Sample Code - getIdentity (Java)

Suppose, you have an authentication system integrated with Sentinel Cloud. You want toauthenticate users before authorizing and granting them access rights. You can use a function say,authenticateUser, for authenticating users and retrieving their credentials after successfulauthentication. You need to implement this function before any authorization call, such as login ortransfer.

A sample implementation of the ‘authenticateUser’ function is given below:

public GetIdentityResponse authenticateUser(String userName, String blob){

GetIdentityResponse response = new GetIdentityResponse();GetIdentityOptionalParam optParam = null; // can be nullString action = null;Configuration config = null;AcquireClientOptionalParam acquireClientOptionalParam = null;AcquireClientResponse acquireClientResponse = null;

try {

/* get license runtime instance */LicenseRuntime runtime = LicenseRuntime.acquireLicenseClient(config, acquireCli-

entOptionalParam, acquireClientResponse);

/* set action for authentication as:"cloud" - for authenticating user from authentication server,

such as in connected mode"local" - for authenticating user locally, such as in disconnected mode

*/action = "cloud";

/* call getIdentity API */runtime.getIdentity(userName, action, blob, optParam, response);

}catch(LicenseException licenseException) {

System.out.println("Error message: " + licenseException.getMessage());System.out.println("Error code: " + licenseException.getErrorCode());return null;

}

System.out.println("+++++++++ GetIdentity Response +++++++++");System.out.println("User: " + response.getUser());System.out.println("Customer: " + response.getCustomer());System.out.println("CookieId: " + response.getCookieId());System.out.println("PayLoad: " + response.getAuthPayload());

return response;}

5.2.2. Sample Code - getIdentity (.NET)

Suppose, you have an authentication system integrated with Sentinel Cloud. You want toauthenticate users before authorizing and granting them access rights. You can use the'authenticateUser' function that authenticates users and retrieves their credentials after successful

authentication. You need to implement this function before any authorization call, such as login ortransfer.


public GetIdentityResponse authenticateUser(String userName, String blob){

GetIdentityResponse response = new GetIdentityResponse();GetIdentityOptionalParam optParam = null; // can be nullString action = null;Configuration config = null;AcquireClientOptionalParam acquireClientOptParam = null;AcquireClientResponse acquireClientResponse = null;

try {

/* get license runtime instance */LicenseRuntime runtime = LicenseRuntime.acquireLicenseClient(config, acquireClientOptParam,

acquireClientResponse);

/* set action for authentication as:"cloud" - for authenticating user from authentication server

such as in connected mode"local" - for authenticating user locally, such as in disconnected mode

*/action = "cloud";

/* call getIdentity API */runtime.getIdentity(userName, action, blob, optParam, response);

}catch(LicenseException licenseException) {

System.Console.WriteLine("Error message: " + licenseException.Message);System.Console.WriteLine("Error code: " + licenseException.errorCode);return null;

}

System.Console.WriteLine("+++++++++ GetIdentity Response +++++++++");System.Console.WriteLine("User: " + response.User);System.Console.WriteLine("Customer: " + response.Customer);System.Console.WriteLine("CookieId: " + response.CookieId);System.Console.WriteLine("PayLoad: " + response.AuthPayLoad);

return response;}

5.2.3. Sample Code - getIdentity (C)

Suppose, you have an authentication system integrated with Sentinel Cloud. You want toauthenticate users before authorizing and granting them access rights. You can use the'authenticateUser' function that authenticates users and retrieves their credentials after successfulauthentication. You need to implement this function before any authorization call, such as login ortransfer.




int authenticateUser(char *userName, /* IN - user to authenticate */char *blob, /* IN - blob for user */char *authenticationMode, /* IN - can be either "cloud" or "local" */

char **user, /* OUT - Identity of authenticated user */char **customer, /* OUT - reference-id of authenticated user

*/char **cookie, /* OUT - cookie-id */char **authPayload) /* OUT - payload(optional) */

{int status = RT_SUCCESS;scr_GetIdentityOptionalParam_t *getIdentityOptParam = NULL;scr_GetIdentityResponse_t *getIdentityResponse = NULL;

scr_AcquireClientOptionalParam_t *acquireClientOptParam = NULL;scr_AcquireClientResponse_t *acquireClientResponse = NULL;scr_Configuration_t *config = NULL;

/* This API should be called once, when application initialized. */status = scr_acquireLicenseClient(config, acquireClientOptParam, &acquireClientResponse);if(status != RT_SUCCESS){

printf("\nError in scr_acquireLicenseClient # %d", status);goto ERROR_EXIT;

}else

printf("\nscr_acquireLicenseClient Successful.");

/* Authenticate user and receive credentials for authorization */status = scr_getIdentity(userName, authenticationMode, blob, getIdentityOptParam, &getIden-

tityResponse);if(status != RT_SUCCESS) {

printf("\nError in scr_getIdentity # %d", status);goto ERROR_EXIT;

}else

printf("\nscr_getIdentity PASSED");

*user = (char*) calloc(sizeof(char), strlen(getIdentityResponse->User) + 1);if(!(*user)){

status = -1;printf("\nCalloc failed");goto ERROR_EXIT;

}strcpy(*user, getIdentityResponse->User);

*customer = (char*) calloc(sizeof(char), strlen(getIdentityResponse->Customer) + 1);if(!(*customer)){


}strcpy(*customer, getIdentityResponse->Customer);

*cookie = (char*) calloc(sizeof(char), strlen(getIdentityResponse->CookieId) + 1);if(!(*cookie)){


}strcpy(*cookie, getIdentityResponse->CookieId);

if(getIdentityResponse->AuthPayload) {*authPayload = (char *) calloc(sizeof(char), strlen(getIdentityResponse->AuthPay-

load) + 1);if(!(*authPayload)) {


}strcpy(*authPayload, getIdentityResponse->AuthPayload);

}

ERROR_EXIT:if(getIdentityResponse) {

if(getIdentityResponse->CookieId)free(getIdentityResponse->CookieId);

if(getIdentityResponse->Customer)free(getIdentityResponse->Customer);

if(getIdentityResponse->User)free(getIdentityResponse->User);

if(getIdentityResponse->AuthPayload)free(getIdentityResponse->AuthPayload);

free(getIdentityResponse);

getIdentityResponse = NULL;}

return status;}

5.3. Sample Code - transferYou can call the transfer API for license detach/return and syncing usage.

This API is available only for on-premise licensing.

5.3.1. Sample Code - transfer (Java) 176

5.3.2. Sample Code - transfer (.NET) 177

5.3.3. Sample Code - scr_transfer (C) 178



5.3.1. Sample Code - transfer (Java)

Following sample shows how to call the transfer API:

public void transferLicense(String user, String customer, int features[], String cookie,String currentLicenseState, String

updatedLicenseState, TransferResponse response){

TransferOptionalParam optParam = null;SaaSFeatureNode featuresToDetach[] = null;Configuration config = null;AcquireClientOptionalParam acquireClientOptionalParam = null;AcquireClientResponse acquireClientResponse = null;

/* sets optional parameters */optParam = new TransferOptionalParam();optParam.setInterval(24); // detaches license for 24 hoursoptParam.setCookie(cookie); // supply if authentication is applicableoptParam.setCurrentLicenseState(currentLicenseState); // supply if using for isol-

ated network with action remote detachoptParam.setUpdatedLicenseState(updatedLicenseState); // supply if using for isol-

ated network with action apply remote license

/* creates array of SaaSFeatureNode for featureIds to transfer */featuresToDetach = new SaaSFeatureNode[features.length];for(int i = 0; i < features.length; i++) {

featuresToDetach[i] = new SaaSFeatureNode(features[i]);}

/* set action to perform */Action action = Action.DETACH; // can be - detach, remote detach, apply remote

license, cancel detach or sync usage

try {/* get license runtime instance */LicenseRuntime runtime = LicenseRuntime.acquireLicenseClient(config,

acquireClientOptionalParam, acquireClientResponse);

/* call transfer API for specified action */runtime.transfer(user, // pass null for server mode

licensecustomer, //pass null if using for isol-

ated network with action apply remote licenseaction,featuresToDetach,optParam,response); // can not be null if using for isolated network

with action remote detach}catch(LicenseException licenseException) {

System.out.println("Error message: " + licenseException.getMessage());System.out.println("Error code: " + licenseException.getErrorCode());

}}

5.3.2. Sample Code - transfer (.NET)

Following sample shows how to use the transfer API:

public void transferLicense(String user, String customer, int[] features, String cookie,String currentLicenseState, String updatedLicenseState, Trans-

ferResponse response){

TransferOptionalParam optParam = null;SaaSFeatureNode[] featuresToDetach = null;

Configuration config = null;AcquireClientOptionalParam acquireClientOptParam = null;AcquireClientResponse acquireClientResponse = null;

/* sets optional parameters */optParam = new TransferOptionalParam();optParam.Interval = 24; // detaches license for 24

hoursoptParam.Cookie = cookie; // supply if authentication

is applicableoptParam.CurrentLicenseState = currentLicenseState; // supply if using for isolated

network with action remote detachoptParam.UpdatedLicenseState = updatedLicenseState; // supply if using for isolated

network with action apply remote license

/* creates array of SaaSFeatureNode for featureIds to transfer */featuresToDetach = new SaaSFeatureNode[features.Length];for (int i = 0; i < features.Length; i++){

featuresToDetach[i] = new SaaSFeatureNode(features[i]);}

/* Set action to perform */Action action = Action.DETACH; // can be - detach, remote detach, apply remote

license, cancel detach or sync usage

try{


entOptParam, acquireClientResponse);

/* call transfer API for specified action */runtime.transfer(user, // pass null for server mode license

customer, //pass null if using for isolated network withaction apply remote license

action,featuresToDetach,optParam,response); // can not be null if using for isolated network

with action remote detach}catch (LicenseException licenseException){

System.Console.WriteLine("Error message: " + licenseException.Message);System.Console.WriteLine("Error code: " + licenseException.errorCode);

}}



5.3.3. Sample Code - scr_transfer (C)

Following sample shows how to use the scr_transfer API:

int transferLicense(char *user, /* IN - Identity of the user to be authorized*/char *customer, /* IN - reference-id of customer to be authorized

*/char *cookie, /* IN - Cookie-id */scr_Features_t features, /* IN - feature-ids to detach/return

license for */int interval, /* IN - interval to detach license for, in hours

*/scr_Action_t transferAction, /* IN - DETACH, CANCEL_DETACH, SYNC_

USAGE, REMOTE_DETACH or APPLY_REMOTE_LICENSE*/char *currentLicenseState, /* IN - Current License

State*/char *updatedLicenseState, /* IN - Updated License

State*/scr_TransferResponse_t **transferResponse) /* OUT -

transfer response */{

int status = 0;scr_TransferOptionalParam_t *transferOptParam = NULL;


/* This API should be called once, when application initialized. */status = scr_acquireLicenseClient(config, acquireClientOptParam, &acquireClientResponse);if(status != RT_SUCCESS){

printf("\n Error in scr_acquireLicenseClient # %d", status);goto ERROR_EXIT;

}else

printf("\nscr_acquireLicenseClient Successful.");

transferOptParam = (scr_TransferOptionalParam_t *) calloc(1, sizeof(scr_Trans-ferOptionalParam_t));

if(transferOptParam == NULL) /* memory allocation failed */{

printf("\nCalloc Failure.");status = -1;goto ERROR_EXIT;

}

transferOptParam->Cookie = cookie; /*supply if authen-tication is applicable*/

transferOptParam->Interval = interval;transferOptParam->CurrentLicenseState = currentLicenseState; /*supply if using for isol-

ated network with action REMOTE_DETACH */transferOptParam->UpdatedLicenseState = updatedLicenseState; /*supply if using for

isolated network with action APPLY_REMOTE_LICENSE */

/* Detach licenses from Cloud */status = scr_transfer(user, /* pass null for server mode license */

customer, /*pass null if using for isol-ated network with action apply remote license*/

transferAction,

features,transferOptParam,transferResponse); /*can not be null if using for

isolated network with action remote detach*/if(status != RT_SUCCESS){

printf("\n Error in scr_transfer # %d", status);goto ERROR_EXIT;

}else

printf("\n scr_transfer PASSED");

ERROR_EXIT:if(transferOptParam){

free(transferOptParam);transferOptParam = NULL;

}

return status;}

5.4. Sample Code - getInfoThis API helps get authorization information of an entitlement. It fetches information based uponprovided scope and returns results in the specified format.

5.4.1. Sample Code - getInfo (Java) 180

5.4.2. Sample Code - getInfo (.NET) 183

5.4.3. Sample Code - scr_getInfo (C) 187



5.4.1. Sample Code - getInfo (Java)

Example 1

Suppose you want to check whether the user is authorized to access a particular feature or not. Forthis, you can use a function ‘isAuthorizationPossible’ in a class.

A sample declaration of the isAuthorizationPossible function is:

public boolean isAuthorizationPossible(

String user,

String customer,

int featureId);

A sample implementation of this function is given below:

public Boolean isAuthorizationPossible(String user, String customer, int featureId){

LicenseRuntime licRuntime = null;Format format = new Format();Vector<Feature> features = null;Boolean isAuthorized = false;GetInfoResponse getInfoResponse = new GetInfoResponse();GetInfoOptionalParam getInfoOptParam = null;Configuration config = null;AcquireClientOptionalParam acquireClientOptionalParam = null;AcquireClientResponse acquireClientResponse = null;

try{

/* get license client instance */licRuntime = LicenseRuntime.acquireLicenseClient(config, acquireClientOptionalParam, acquireCli-

entResponse);

/** Check if user is authorized. If user cannot be authorized, API* will return false. If user can be authorized this API will* return true. In case of any error this API will throw LicenseException.* The exception will contain information/cause of the failure.*/

// Set the output formats to get authorization detailformat.setFormat(FormatType.FEATURE_AUTHORIZATION.getCode());

// Set optinal param if capacity peek info is needed,//otherwise pass NULLgetInfoOptParam = new GetInfoOptionalParam();getInfoOptParam.setCapacityInterval(48); // Last 2 days

// Get all the entitlements for the given customer and userlicRuntime.getInfo(user, customer, null, format,

getInfoOptParam, getInfoResponse);

// Retrieves Feature vector from responseif(getInfoResponse != null){

features = getInfoResponse.getFeatureInfoList();}

// To check if a license is available or not for the userisAuthorized = isUserAuthorized(features, featureId);

// De-initializes and release the Cloud Run-time instanceLicenseRuntime.releaseLicenseClient();

return isAuthorized;}catch (LicenseException e){

return false;}

}

/*** This function will iterate through the entitlement list and retrieve* the record to check authorization for given feature** @param features* A list of features** @param featureId* feature id** @throws LicenseException*/

private Boolean isUserAuthorized(Vector<Feature> features, Integer featureId){

Boolean isAccessible = false;Iterator<Feature> featureIteartor = features.iterator();while (featureIteartor.hasNext()){

Feature feature = featureIteartor.next();if (feature.getFeatureId().equals(featureId) &&

(feature.IsUsable().equals(true) == true)){

isAccessible = true;break;

}}return isAccessible;

}

Example 2

Suppose you want to retrieve details of a particular feature of a particular entitlement and product fora user. This refers to the following use case of the Scope class:

entitlementId productName featureId Result

Not null Not null Not null Information for the given featureID,productName, and entitlementId.

To implement this, you can define a function ‘getEntitlements’ in a class.

A sample declaration of the getEntitlements function is:



public Vector<Entitlement> getEntitlements(

String user,

String customer,

String entitlementId,

String productId,

int featureId);

A sample implementation of ‘getEntitlements’ is:

public Vector<Entitlement> getEntitlements(String user, String customer, String entitlementId,String productId, int featureId)

{LicenseRuntime licRuntime = null;Format format = new Format();Scope scope = new Scope();Vector<Entitlement> entitlements = null;GetInfoResponse getInfoResponse = new GetInfoResponse();Configuration config = null;AcquireClientOptionalParam acquireClientOptionalParam = null;AcquireClientResponse acquireClientResponse = null;try{

/* get license client instance */licRuntime = LicenseRuntime.acquireLicenseClient(config, acquireClientOptionalParam, acquireCli-

entResponse);

/* Set either featureId or featureName */SaaSFeatureNode featureNode = new SaaSFeatureNode();featureNode.setFeatureId(featureId);scope.add(entitlementId, productId, featureNode);

// Set the output formatsformat.setFormat(FormatType.FEATURE_DETAILS.getCode());

// Get all the entitlements for the given customer and userlicRuntime.getInfo(user, customer, scope, format, null, getInfoResponse);

if(getInfoResponse != null){

entitlements = getInfoResponse.getEntitlementList();}


}catch (LicenseException e){

// exception handling}

return entitlements;}

Example 3

The following code snippet shows the function getCurrentLicenseState to demonstrate use of getInfofor retrieving current license state of an isolated on-premisemachine.

public void getCurrentLicenseState(GetInfoResponse getInfoResponse){

String user = null;//pass as null

String customer = null;//pass as null

Scope scope = null;// pass as null

Format format = new Format();GetInfoOptionalParam getInfoOptional = null;

//pass as nullConfiguration config = null;AcquireClientOptionalParam acquireClientOptionalParam = null;AcquireClientResponse acquireClientResponse = null;

try {// get license runtime instanceLicenseRuntime runtime = LicenseRuntime.acquireLicenseClient(config,

acquireClientOptionalParam, acquireClientResponse);

// set correct format to get current license stateformat.setFormat(FormatType.CURRENT_LICENSE_STATE.getCode());// call getInfo to get current license state of machineruntime.getInfo(user, customer, scope, format, getInfoOptional, getIn-

foResponse);}catch(LicenseException licenseException) {

System.out.println("Error message: " + licenseException.getMessage());System.out.println("Error code: " + licenseException.getErrorCode());

}}

5.4.2. Sample Code - getInfo (.NET)

Example 1

Suppose you want to check whether the user is authorized to access a particular feature or not. Forthis, you can use a function ‘isAuthorizationPossible’ in a class.


public boolean isAuthorizationPossible(

String user,

String customer,

int featureId);


public Boolean isAuthorizationPossible(String user, String customer, int featureId ){

LicenseRuntime licRuntime = null;Format format = new Format();List<Feature> featureList = null;Boolean isAuthorized = false;GetInfoResponse getInfoResponse = new GetInfoResponse();



GetInfoOptionalParam getInfoOptParam = null;Configuration config = null;AcquireClientOptionalParam acquireClientOptParam = null;AcquireClientResponse acquireClientResponse = null;

try{

/* get license client instance */licRuntime = LicenseRuntime.acquireLicenseClient(config, acquireClientOptParam,


/** Check if user is authorized. If user cannot be authorized, API* will return false. If user can be authorized this API will* return true. In case of any error this API will throw LicenseException.* The exception will contain information/cause of the failure.*/

// Set the output formats to get authorization detailformat.FormatStyle = (int)FormatType.FEATURE_AUTHORIZATION;

// Set optinal param if capacity peek info is needed,//otherwise pass NULLgetInfoOptParam = new GetInfoOptionalParam();getInfoOptParam.capacityInterval = 48; // Last 2 days

// Get all the entitlements for the given customer and userlicRuntime.getInfo(user, customer, null, format, getInfoOptParam, getInfoResponse);

// Retrieves Entitlement vector from responseif(getInfoResponse != null){

featureList = getInfoResponse.FeatureInfoList;}// To check if a license is available or not for the userisAuthorized = isUserAuthorized(featureList, featureId);


return isAuthorized;}catch (LicenseException){

return false;}

}

/// <summary>/// This function will iterate through the entitlement list and retrieve the record/// to check authorization for given feature/// </summary>/// <param name="features"></param>/// <param name="featureId"></param>/// <returns></returns>private Boolean isUserAuthorized(List<Feature> features, Int32 featureId){

Boolean isAccessible = false;

foreach (Feature feature in features)

{if ((feature.FeatureId == featureId) && (feature.IsUsable == "true")){

isAccessible = true;break;

}}return isAccessible;

}

Example 2

Suppose you want to retrieve details of a particular feature of a particular entitlement and product fora user. This refers to the following use case of the Scope class:


Not null Not null Not null Informationfor the givenfeatureID,productName,andentitlementId.

To implement this, you can define a function ‘getEntitlements’ in a class.

A sample declaration of this function is:

public List <Entitlement> getEntitlements(

String user,

String customer,

String entitlementId,

String productId,

int featureId);


public List<Entitlement> getEntitlements(String user, String customer,String entitlementId, String productId, int featureId)

{LicenseRuntime licRuntime = null;Format format = new Format();Scope scope = new Scope();List<Entitlement> entitlements = null;GetInfoResponse getInfoResponse = new GetInfoResponse();


try{





// Set scopeSaaSFeatureNode featureNode = new SaaSFeatureNode();featureNode.iFeatureId = featureId;scope.Add(entitlementId, productId, featureNode);

// Set the output formatsformat.FormatStyle = (int)FormatType.FEATURE_DETAILS;

// Get all the entitlements for the given customer and userlicRuntime.getInfo(user, customer, scope, format, null,

getInfoResponse);

if(getInfoResponse != null){

entitlements = getInfoResponse.entitlementList;}


}catch (LicenseException){

// exception handling}

return entitlements;}

Example 3


public void getCurrentLicenseState(GetInfoResponse getInfoResponse){

string user = null; // pass as nullstring customer = null; // pass as nullScope scope = null; // pass as nullFormat format = new Format();GetInfoOptionalParam getInfoOptParam = null; //pass as nullConfiguration config = null;AcquireClientOptionalParam acquireClientOptParam = null;AcquireClientResponse acquireClientResponse = null;

try{



// set correct format to get current license stateformat.FormatStyle = (int)FormatType.CURRENT_LICENSE_STATE;// call getInfo to get current license stateruntime.getInfo(user, customer, scope, format, getInfoOptParam, getInfoResponse);

}catch (LicenseException licenseException){

System.Console.WriteLine("Error message: " + licenseException.Message);System.Console.WriteLine("Error code: " + licenseException.errorCode);

}}

5.4.3. Sample Code - scr_getInfo (C)

Example 1

Suppose you want to check whether the user is authorized to access a particular feature or not. Forthis, you can use a function say, ‘isAuthorizationPossible’.


int isAuthorizationPossible(

char *user,

char *customer,

int featureId)


int isAuthorizationPossible(char *user, char *customer, int featureId){

int returnCode = -1;scr_Scope_t *scope = NULL;scr_Format_t format;scr_Feature_t *features = NULL;scr_GetInfoResponse_t *getInfoResponse = NULL;scr_GetInfoOptionalParam_t *getInfoOptionalparam = NULL;int isAuthorized = 0; /* 0 for false , 1 for true */

/* first initialize, if it is not called before */returnCode = scr_acquireLicenseClient();if(returnCode != RT_SUCCESS){

printf("\n Error in scr_acquireLicenseClient # %d", returnCode);goto exit;

}else{


/* Check if user is authorized. If user cannot be authorized,API will return false. If user can be authorized this APIwill return true. In case of any error this API will returnerror.*/

/* Set the output formats to get authorization detail*/format.FormatStyle = FEATURE_AUTHORIZATION;

/* Set optinal parameter if capacity peek info is needed,otherwise pass NULL */getInfoOptionalparam = (scr_GetInfoOptionalParam_t *) calloc(1, sizeof(scr_GetInfoOptionalParam_

t));if (getInfoOptionalparam == NULL){



printf("\nMemory allocation failed");goto exit;

}

getInfoOptionalparam->CapacityInterval = 48; // last 2 days

/* Get all the entitlements/features for the given customer and user */

/* Caller must free the response to avoid memory leak */returnCode = scr_getInfo(user, customer, NULL, format,

getInfoOptionalparam, &getInfoResponse);if(returnCode != RT_SUCCESS){

printf("\nError in scr_getInfo # %d", returnCode);goto exit;

}else{

printf("\n scr_getInfo is successful");if(getInfoResponse != NULL){

/* retrieves feature list from response */features = getInfoResponse->FeatureInfoList;

}}

/* To check if a license is available or not for the user */isAuthorized = isUserAuthorized(features, featureId);

/* De-initializes and release the Cloud Run-time */returnCode = scr_releaseLicenseClient();if(returnCode != RT_SUCCESS){

printf("\nError in scr_releaseLicenseClient # %d", returnCode);}else{

printf("\n scr_releaseLicenseClient is successful.");}

exit:if (getInfoOptionalparam != NULL)

free(getInfoOptionalparam);

return isAuthorized;}

/* This function will iterate through the entitlement list and retrieve the recordto check authorization for given feature*/int isUserAuthorized(scr_Feature_t *features, int featureId){

int isAccessible = 0;

while (features != NULL){

if ((features->FeatureId == featureId) &&(features->IsUsable == 1))

{isAccessible = 1;

break;}

features = features->Next;}

return isAccessible;} int isAuthorizationPossible(char *user, char *customer, int featureId){

int returnCode = -1;scr_Scope_t *scope = NULL;scr_Format_t format;scr_Feature_t *features = NULL;scr_GetInfoResponse_t *getInfoResponse = NULL;scr_GetInfoOptionalParam_t *getInfoOptionalparam = NULL;int isAuthorized = 0; /* 0 for false , 1 for true */scr_AcquireClientOptionalParam_t *acquireClientOptParam = NULL;scr_AcquireClientResponse_t *acquireClientResponse = NULL;scr_Configuration_t *config = NULL;

/* first initialize, if it is not called before */returnCode = scr_acquireLicenseClient(config, acquireClientOptParam, &acquireClientResponse);if(returnCode != RT_SUCCESS){


}else{


/* Check if user is authorized. If user cannot be authorized,API will return false. If user can be authorized this APIwill return true. In case of any error this API will returnerror.*/

/* Set the output formats to get authorization detail*/format.FormatStyle = FEATURE_AUTHORIZATION;

/* Set optinal parameter if capacity peek info is needed,otherwise pass NULL */getInfoOptionalparam = (scr_GetInfoOptionalParam_t *) calloc(1, sizeof(scr_GetInfoOptionalParam_

t));if (getInfoOptionalparam == NULL){

printf("\nMemory allocation failed");goto exit;

}

getInfoOptionalparam->CapacityInterval = 48; // last 2 days

/* Get all the entitlements/features for the given customer and user */

/* Caller must free the response to avoid memory leak */returnCode = scr_getInfo(user, customer, NULL, format,

getInfoOptionalparam, &getInfoResponse);if(returnCode != RT_SUCCESS)



{printf("\nError in scr_getInfo # %d", returnCode);goto exit;

}else{


/* retrieves feature list from response */features = getInfoResponse->FeatureInfoList;

}}

/* To check if a license is available or not for the user */isAuthorized = isUserAuthorized(features, featureId);




exit:if (getInfoOptionalparam != NULL)

free(getInfoOptionalparam);

return isAuthorized;}

/* This function will iterate through the entitlement list and retrieve the recordto check authorization for given feature*/int isUserAuthorized(scr_Feature_t *features, int featureId){

int isAccessible = 0;

while (features != NULL){

if ((features->FeatureId == featureId) &&(features->IsUsable == 1))

{isAccessible = 1;break;

}

features = features->Next;}

return isAccessible;}

Example 2

Suppose you want to retrieve details of a particular feature of a particular entitlement and product fora user. This refers to the following use case of the Scope structure:


Not null Not null Not null Returninformationfor the givenfeatureID,productName,andentitlementId.

To implement this, you can define a function ‘getEntitlements’.

A sample declaration of the getEntitlements function is:

scr_Entitlement_t *getEntitlements(

char *user,

char *customer,

char *entitlementId,

char *productId,

int featureId);


scr_Entitlement_t* getEntitlements(char* user, char* customer,char *entitlementId, char *productId,int featureId)

{int returnCode = -1;scr_Scope_t *scope = NULL;scr_Format_t format;scr_Entitlement_t *entitlement = NULL;scr_GetInfoResponse_t *getInfoResponse = NULL;scr_AcquireClientOptionalParam_t *acquireClientOptParam = NULL;scr_AcquireClientResponse_t *acquireClientResponse = NULL;scr_Configuration_t *config = NULL;

scope = (scr_Scope_t *) calloc(1, sizeof(scr_Scope_t));if(scope == NULL) /* memory allocation failed */

return NULL;

scope->EID = entitlementId;scope->ProductName = productId;

scope->FeatureNode = (scr_FeatureNode_t *) calloc(1, sizeof(scr_FeatureNode_t));if (scope->FeatureNode == NULL)

return NULL;// Set either featureId or featureNamescope->FeatureNode->FeatureId = featureId;

scope->Next = NULL;



/* Set the output formats */format.FormatStyle = FEATURE_DETAILS;



}else{


/* Get all the entitlements for the given user andcustomer according to scope and format set */

/* Caller must free the response to avoid memory leak */returnCode = scr_getInfo(user, customer, scope, format,

NULL, &getInfoResponse);if(returnCode != RT_SUCCESS){


}else

printf("\n scr_getInfo is successful");




entitlement = getInfoResponse->EntitlementInfoList;}

}

exit:return entitlement;

}

Example 3


int getCurrentLicenseState(scr_GetInfoResponse_t **getInfoResponse /* OUT - response */){

char *user = NULL;/* pass user as NULL */

char *customer = NULL; /* passcustomer as NULL */

int returnCode = -1;scr_Scope_t *scope = NULL; /* pass

scope as NULL */scr_Format_t format;scr_GetInfoOptionalParam_t *getInfoOptionalparam = NULL; /* pass NULL */scr_AcquireClientOptionalParam_t *acquireClientOptParam = NULL;scr_AcquireClientResponse_t *acquireClientResponse = NULL;scr_Configuration_t *config = NULL;

/* first initialize, if it is not called before */returnCode = scr_acquireLicenseClient(config, acquireClientOptParam, &ac-



}else{


/* Set the output formats to get current license state*/format.FormatStyle = CURRENT_LICENSE_STATE;

/* Call getInfo to get current license state */returnCode = scr_getInfo(user, customer, scope, format,

getInfoOptionalparam, getInfoResponse);if(returnCode != RT_SUCCESS){


}else{

printf("\n scr_getInfo is successful");}

exit:return returnCode;

}

5.5. Sample Code - login5.5.1. Sample Code - login (Java) 194

5.5.2. Sample Code - login (.NET) 195

5.5.3. Sample Code - scr_login (C) 197



5.5.1. Sample Code - login (Java)

Suppose you have authenticated the user and now user wants to consume a particular feature. Add afunction say ‘authorizeUser’ in a class. This function will try to consume the feature, and will throw anexception if the feature is not available.

If you just want to enable/disable a feature based on if it is available to that user ID or not, usethe getInfo API as it does not consume any license. The login API is used to consume licenses.

A sample declaration of ‘authorizeUser’ is given below:

public boolean authorizeUser(

String user,

String customer,

int featureId,

int capacity,

String vendorInfo,

HttpServletRequest httpRequest);

Where,

n user - Identifies the user requesting authorization

n customer - Identifies a customer

n featureId – Identifies the feature user is trying to authorize

n vendorInfo - Contains vendor information

n capacity - Contains feature capacity

n httpRequest - Contains http request object that is used to store session ID

A sample implementation of ‘authorizeUser’ function is given below:

public boolean authorizeUser(String user, String customer, int featureId,int capacity, String vendorInfo, HttpServletRequest httpRequest)

{LicenseRuntime licRuntime = null;SaaSFeatureNode featureNode = new SaaSFeatureNode(featureId);String sessionHandle = null;LoginOptionalParam loginOptParam = new LoginOptionalParam();LoginResponse loginResponse = new LoginResponse();

Configuration config = null;AcquireClientOptionalParam acquireClientOptionalParam = null;AcquireClientResponse acquireClientResponse = null;

try{

/* get license client instance */licRuntime = LicenseRuntime.acquireLicenseClient(config, acquireCli-


/** authorize user. If user is authorized session handle will be returned* by this API. If user is not authorized this API will throw

* LicenseException. The exception will contain information/ cause of the* failure.*/loginOptParam.setVendorData(vendorInfo);

if(capacity > 0)loginOptParam.setCapacity(capacity);

licRuntime.login(user, customer, featureNode, loginOptParam,loginResponse);


return false;}/** Store this session handle at some place for future reference e.g. while* calling logout API we will need this session handle to expire user* session. Here we will use httpRequest object to store session handle as* an attribute. So that when this user again requests ISV application can* use this session handle. To communicate with client.*/if (loginResponse != null){

sessionHandle = loginResponse.getSessionHandle();}httpRequest.setAttribute("sessionHandle", sessionHandle);return true;

}

5.5.2. Sample Code - login (.NET)

Suppose you have authenticated the user and now user wants to consume a particular feature. Add afunction say ‘authorizeUser’ in a class. This function will try to consume the feature, and will throw anexception if the feature is not available.

If you just want to enable/disable a feature based on if it is available to that user or not, usethe getInfo API as it does not consume any license. The login API is used to consume licenses.


public boolean authorizeUser(

String user,

String customer,

int featureId,

int capacity

String vendorInfo,


Where,

n user - Identifies the user requesting authorization

n customer - Identifies a customer



n featureId – Identifies the feature user is trying to authorize



n httpRequest - Contains http request object that is used to store session ID

A sample implementation of ‘authorizeUser’ function is given below:

public Boolean authorizeUser(String user, String customer, int featureId,int capacity, String vendorInfo)

{LicenseRuntime licRuntime = null;SaaSFeatureNode featureNode = new SaaSFeatureNode(featureId);String sessionHandle = null;LoginOptionalParam loginOptParam = new LoginOptionalParam();LoginResponse loginResponse = new LoginResponse();


try{



/* set vendorInfo as optional parameter */loginOptParam.VendorData = vendorInfo;

/* set capacity */if (capacity > 0)

loginOptParam.Capacity = capacity;

/** authorize user.* If user is authorized session handle will be returned by this* API. If user is not authorized this API will throw* LicenseException. The exception will contain information/cause* of the failure.*/licRuntime.login(user, customer, featureNode, loginOptParam, loginResponse);

/* retrieves session handle from response */sessionHandle = loginResponse.SessionHandle;


return false;}

/** Store this session handle at some place for future reference* e.g. while calling logout API we will need this session handle* to expire user session.*/return true;

}

5.5.3. Sample Code - scr_login (C)

Suppose you have authenticated the user and now user wants to consume a particular feature. Add afunction say ‘authorizeUser’. This function will try to consume the feature, and will throw an error ifthe feature is not available.

If you just want to enable/disable a feature based on if it is available to an user or not, use thegetInfo API as it does not consume any license. The login API is used to consume licenses.


int authorizeUser(

char *user,

char *customer,

scr_FeatureNode_t feature,

int capacity

char *vendorInfo)

Where,

n user- Identifies the user requesting authorization

n customer- Identifies a customer

n feature – Identifies the feature user is trying to authorize



A sample implementation of the ‘authorizeUser’ function is given below:

int authorizeUser(char* user, char* customer, scr_FeatureNode_t feature, int capacity, char*vendorInfo){

int returnCode = -1;char* sessionHandle = NULL;scr_LoginOptionalParam_t* optinalParam = NULL;scr_LoginResponse_t* loginResponse = NULL;


/* initialize */returnCode = scr_acquireLicenseClient(config, acquireClientOptParam, &ac-



}else{




/* authorize user. If user is authorized session handle will be returned by this *//* API. If user is not authorized this API will return error code. */optinalParam = (scr_LoginOptionalParam_t *)calloc(1, sizeof(scr_LoginOptionalParam_t));if(optinalParam == NULL){

printf("\n Memory allocation failed.");goto exit;

}

/* sets vendor specific info in optional param */optinalParam->VendorData = vendorInfo;

/* set capacity */if(capacity > 0)

optinalParam->Capacity = capacity;

/* authorizes user for given feature id *//* Caller must free memory for optinalParam and loginResponse to avoid memory leaks */returnCode = scr_login(user, customer, &feature, optinalParam, &loginResponse);if(returnCode != RT_SUCCESS){

printf("\nError in scr_login # %d", returnCode);goto exit;

}else{

if(loginResponse != NULL){

if(loginResponse->SessionHandle != NULL)printf("\n scr_login is successful. Session Handle: %s", loginResponse-

>SessionHandle);}

}

/* Store this session handle at some place for future reference* e.g. while calling scr_logout API we will need this session handle* to expire user session.*/

exit:if(returnCode != RT_SUCCESS)

return 0;else

return 1;}

5.6. Sample Code - refreshSessionYou can call the refreshSession API between login and logout calls for refreshing concurrent sessions.

This API is available only for Cloud licensing.

5.6.1. Sample Code - refreshSession (Java) 199

5.6.2. Sample Code - refreshSession (.NET) 200

5.6.3. Sample Code - scr_refreshSession(C) 200

5.6.1. Sample Code - refreshSession (Java)

Following sample shows how to call the refreshSession API:

/* refreshSession API can be called periodically to update a particular* session, also it tells whether given sessionHandle is still valid or* already terminated.** Assumption: login has already been called before calling this method.*/

public Boolean refreshSession(String sessionHandle){

LicenseRuntime licenseRuntime = null;Configuration config = null;AcquireClientOptionalParam acquireClientOptionalParam = null;AcquireClientResponse acquireClientResponse = null;

try{

/* get license client instance */licenseRuntime = LicenseRuntime.acquireLicenseClient(config, acquireCli-


RefreshSessionResponse refreshSessionResponse = new RefreshSessionResponse();

/* call refreshSession method to refresh this particular session, also if* doesn't throw any exception, user can continue consume feature.*/

licenseRuntime.refreshSession(sessionHandle, null, refreshSessionResponse);

return true;}catch (LicenseException licenseException){

/** Here example is shown for handling of network error, developer can* handle other error codes as per their requirements.*/

/** If there is a network issue, it's not necessary to close session,* instead user can be allowed to continue use corresponding feature.*/

if (licenseException.getErrorCode() == 2001){

// Notification can be sent to administrator via email or some other// way.// Developer needs to handle notification him/her self.return true;

}// Return false, so that application won't allow user to continue on this// feature.return false;

}}

5.6. Sample Code - refreshSession 199


5.6.2. Sample Code - refreshSession (.NET)

Following sample shows how to use the refreshSession API:

/* refreshSession API can be called periodically to update a particular* session, also it tells whether given sessionHandle is still valid or* already terminated.** Assumption: login has already been called before calling this method.*/

public Boolean refreshSession(String sessionHandle){

LicenseRuntime licenseRuntime = null;Configuration config = null;AcquireClientOptionalParam acquireClientOptParam = null;AcquireClientResponse acquireClientResponse = null;

try{

/* get license client instance */licenseRuntime = LicenseRuntime.acquireLicenseClient(config, acquireCli-


RefreshSessionResponse refreshSessionResponse = new RefreshSessionResponse();

/* call refreshSession method to refresh this particular session, also if* doesn't throw any exception, user can continue consume feature.*/

licenseRuntime.refreshSession(sessionHandle, null, refreshSessionResponse);

return true;}catch (LicenseException licenseException){

/** Here example is shown for handling of network error, developer can* handle other error codes as per their requirements.*/

/** If there is a network issue, it's not necessary to close session,* instead user can be allowed to continue use corresponding feature.*/

if (licenseException.errorCode == 2001){

// Notification can be sent to administrator via email or some other// way.// Developer needs to handle notification him/her self.return true;

}// Return false, so that application won't allow user to continue on this// feature.return false;

}}

5.6.3. Sample Code - scr_refreshSession(C)

Following sample shows how to use the scr_refreshSession API:

/*refreshSession API can be called periodically to update a particular* session, also it tells whether given sessionHandle is still valid or* already terminated.** Assumption: acquireLicensClient and login APIs are already called before calling this method.*/int refreshSession(char* sessionHandle){

int returnCode = -1;scr_RefreshSessionOptionalParam_t* optinalParam = NULL;scr_RefreshSessionResponse_t* refreshSessionResponse = NULL;

optinalParam = (scr_RefreshSessionOptionalParam_t *)malloc(sizeof(scr_RefreshSes-sionOptionalParam_t));

if(optinalParam == NULL){

return returnCode;}

/* refreshes session for the given session handle *//* Caller must free memory for optParam and response to avoid memory leaks */returnCode = scr_refreshSession(sessionHandle, optinalParam, &refreshSessionResponse);

if(returnCode != RT_SUCCESS){

/** Here example is shown for handling of network error, developer can* handle other error codes as per their requirements e.g communication* error is allowed continuously only two times etc.*/

/** If there is a network issue, it's not necessary to close session,* instead user can be allowed to continue use corresponding feature.*/if ( returnCode == RT_ERR_IN_COMMUNICATION ){

returnCode = RT_SUCCESS;}

}if ( refreshSessionResponse != NULL ){

free(refreshSessionResponse);}if ( optinalParam != NULL ){

free(optinalParam);}return returnCode;

}

5.7. Sample Code - logout5.7.1. Sample Code - logout (Java) 202

5.7.2. Sample Code - logout (.NET) 203



5.7.3. Sample Code - scr_logout (C) 203

5.7.1. Sample Code - logout (Java)

Assume that you have already authenticated and authorized a user for a feature. Now, you want toterminate the user session that was setup by the login API call. For this, add the logout API withsession handle as an argument (session handle is the string returned by login API).

You can include a function, say expireUserSession, in a class. The job of this function will be toterminate the user session.

A sample declaration of ‘expireUserSession’ is given below:

public boolean expireUserSession(


Where,

n httpRequest - is the object containing http request sent by client. This will contain sessionhandle acquired while calling login API.

A sample implementation of the ‘expireUserSession’ function is given below:

public boolean expireUserSession(HttpServletRequest httpRequest) {String sessionHandle = null;LicenseRuntime licRuntime = null;LogoutOptionalParam logoutOptParam = new LogoutOptionalParam();LogoutResponse logoutResponse = new LogoutResponse();

Configuration config = null;AcquireClientOptionalParam acquireClientOptionalParam = null;AcquireClientResponse acquireClientResponse = null;

/* get session handle */sessionHandle = (String) httpRequest.getAttribute("sessionHandle");try {

/* get license client instance */licRuntime = LicenseRuntime.acquireLicenseClient(config, acquireCli-


/* create object for custom attributes */Attributes attribute = new Attributes();

/* set custom attribute for usage multiplier */attribute.logOutAttributes.setUsageCountMultiplier(1);

/* set attribute as optional logout parameter */logoutOptParam.setAttributes(attribute);

/* call logout API to expire user session */licRuntime.logout(sessionHandle, logoutOptParam, logoutResponse);

} catch (LicenseException e) {return false;

}return true;

}

5.7.2. Sample Code - logout (.NET)

Assume that you have already authenticated and authorized a user for a feature. Now, you want toterminate the user session that was setup by the login API call. For this, add the logout API withsession handle as an argument (session handle is the string returned by login API).

You can include a function, say ‘expireUserSession’, in a class. The job of this function will be toterminate the user session.

A sample declaration of ‘expireUserSession’ is given below:

public boolean expireUserSession(


Where,

n httpRequest - is the object containing http request sent by client. This will contain sessionhandle acquired while calling login API.

A sample implementation of the ‘expireUserSession’ function is given below:

public Boolean expireUserSession(String SessionHandle){

LicenseRuntime licRuntime = null;LogoutOptionalParam logoutOptParam = new LogoutOptionalParam();

LogoutResponse logoutResponse = new LogoutResponse();Configuration config = null;AcquireClientOptionalParam acquireClientOptParam = null;AcquireClientResponse acquireClientResponse = null;

try {/* get license client instance */licRuntime = LicenseRuntime.acquireLicenseClient(config, acquireClientOptParam,


/* create object for custom attributes */logoutOptParam.Attribute = new Attributes();

/* set attribute as optional logout parameter */logoutOptParam.Attribute.logOutAttributes.UsageCountMultiplier = 2;

/* call logout API to expire user session */licRuntime.logout(sessionHandle, logoutOptParam, logoutResponse);

}catch (LicenseException e) {return false;

}return true;

}

5.7.3. Sample Code - scr_logout (C)

Assume that you have already authenticated and authorized a user for a feature. Now, you want toterminate the user session that was setup by the scr_loginAPI call. For this, add the scr_logoutAPIwith session handle as an argument (session handle is the string returned by scr_loginAPI).



You can include a function, say ‘expireUserSession’, The job of this function will be to terminate theuser session. A sample implementation of the ‘expireUserSession’ function is given below:

void expireUserSession(char *sessionHandle){

int returnCode = -1;scr_LogoutOptionalParam_t* logoutOptParam = NULL;scr_LogoutResponse_t *logoutResp = NULL;scr_AcquireClientOptionalParam_t *acquireClientOptParam = NULL;scr_AcquireClientResponse_t *acquireClientResponse = NULL;scr_Configuration_t *config = NULL;



}else{


/* allocates memory for optional parameter */logoutOptParam = (scr_LogoutOptionalParam_t *)malloc(sizeof(scr_LogoutOptionalParam_t));if(logoutOptParam == NULL) /* memory allocation failed */{

printf("\n Memory allocation failed.");goto exit;

}

/* lets set 2 to usageCountMultiplier */logoutOptParam->Attribute.UsageCountMultiplier = 2;

/* call scr_logout API to expire user session *//* Caller of scr_logout must free memory for logoutOptParam and logoutResp */returnCode = scr_logout(sessionHandle, logoutOptParam, &logoutResp);if(returnCode != RT_SUCCESS){

printf("\n Error in scr_logout # %d", returnCode);goto exit;

}else{

printf("\n scr_logout is success.");}

exit:if(logoutOptParam != NULL){

free(logoutOptParam);logoutOptParam = NULL;

}if(logoutResp != NULL)

{free(logoutResp);logoutResp = NULL;

}

return;}

5.8. Sample Code - releaseLicenseClientYou can call this API at the time of application de-initialization.

5.8.1. Sample Code - releaseLicenseClient (Java) 206

5.8.2. Sample Code - releaseLicenseClient (.NET) 206

5.8.3. Sample Code - scr_releaseLicenseClient (C) 206

5.8. Sample Code - releaseLicenseClient 205


5.8.1. Sample Code - releaseLicenseClient (Java)

The ‘destroy’ function of servlets is one of the possible places where we can insert this API call.Following sample shows how to de-initialize Cloud Run-time in ‘destroy’ function.

public void destroy() {/* check if license client is initialized or not */if (licRuntime != null) {

/* de-initialize license client */try {

LicenseRuntime.releaseLicenseClient();} catch (LicenseException e) {

e.printStackTrace();}licRuntime = null;

}}

5.8.2. Sample Code - releaseLicenseClient (.NET)

The ‘destroy’ function of servlets is one of the possible places where we can insert this API call.Following sample shows how to de-initialize Cloud Run-time in ‘destroy’ function.

public void destroy(LicenseRuntime licRuntime){

/* check if license client is initialized or not */if (licRuntime != null){

/* de-initialize license client */LicenseRuntime.releaseLicenseClient();licRuntime = null;

}}

5.8.3. Sample Code - scr_releaseLicenseClient (C)

Following sample shows how to de-initialize Cloud Run-time .

void release(){

int returnCode = -1;

returnCode = scr_releaseLicenseClient();if(returnCode != RT_SUCCESS){



return ;}

Chapter 6:Integrating Cloud Run-time APIs

This section contains the following information about integrating Cloud Run-time APIs in your sourcecode:

6.1. Specific Requirements 208

6.2. Integration Steps 212

6.3. Best Practices 216

6

208 Chapter 6: Integrating Cloud Run-time APIs

6.1. Specific RequirementsThis section lists down the software and file requirements for integrating the Run-time APIs.

6.1.1. Specific Requirements (Java) 209

6.1.2. Specific Requirements (.NET) 210

6.1.3. Specific Requirements (C) 210

To view a consolidated list of files required to build a Cloud or On-premise application on differentinterfaces, please refer Appendix D: Build Dependencies .

6.1.1. Specific Requirements (Java)

Software Requirements

n JDK 1.6

n Quartz 1.7.3

n XLightWeb 2.13.2

n XStream 1.0.2

n JCS 1.3

n Log4j 1.2.13

n Apache Commons Logging 1.1.1

n Bouncy castle 1.4.5

n SaaSCommon.jar

n SaaSxStream.jar

Required Files

n SentinelCloudRuntime-[version].jar

Windows

n SentinelCloudRuntime_P.dll (for On-premise 32-bit applications)

n SentinelCloudRuntime_P_x64.dll (for On-premise 64-bit applications)

Linux

n SentinelCloudRuntime_P.so (for On-premise 32-bit applications)

n SentinelCloudRuntime_P_x64.so (for On-premise 64-bit applications)

Configuration Files

Please refer to the section Name and Location of the Client Configuration File for information aboutthe configuration file(s) required to run Java applications.

Environment Variable for Linux

An on-premise application deployed on Linux and running on Tomcat should be able to read the LC_CTYPE environment variable. This environment variable stores the system locale.



6.1.2. Specific Requirements (.NET)


n Microsoft .NET Framework 2.0 or 3.5

n Microsoft Enterprise Library 3.1 -May 2007

n Log4net 1.2.10

n Quartz.NET 1.0

Required Files

n SentinelCloudRuntime.dll

n SentinelCloudRuntime_P.dll (for on-premise application)

n SentinelCloudRuntime_P_x64.dll (for on-premise application)

n Common.Logging.dll

n Quartz.dll

n Quartz.xml

n Log4net.dll

n Microsoft.Practices.EnterpriseLibrary.Common.dll

n Microsoft.Practices.EnterpriseLibrary.Caching.dll

n Microsoft.Practices.ObjectBuilder.dll

n BouncyCastle.Crypto.dll

Required Configuration Files

Please refer to the section Name and Location of the Client Configuration File for information aboutthe configuration file(s) required to run .NET applications.

6.1.3. Specific Requirements (C)

This section lists down the software and file requirements for integrating the Cloud Run-time APIs:


n Visual Studio 2005 or later

Required Libraries

Windows

Cloud and On-premise32-bit

Cloud and On-premise

n scrruntime.libn scrdserializer.libn scrserializer.libn libhasp_windows.lib

64-bit

n scrruntime_x64.libn scrdserializer_x64.libn scrserializer_x64.libn libhasp_windows_x64.lib

Linux


n libscrdserializer.an libscrruntime.an libscrserializer.an libhasp_linux.a

64-bit

n libscrdserializer_x64.an libscrruntime_x64.an libscrserializer_x64.an libhasp_linux_x86_x64.a

Required Third Party Libraries

Windows


n genx.libn libcurl.libn libeay32MT.libn libexpatMT.libn liblogger.libn ssleay32MT.libn Wtsapi32.lib

64-bit

n liblogger.libn genx.libn libexpatMT.libn libcurl.lib




n libeay32.libn ssleay32.libn Wtsapi32.lib

Linux


n libcrypto.an libcurl.an libexpat.an libgenx.an libjs.an liblogger.an libssl.a

Required Configuration Files

Please refer to the section Name and Location of the Client Configuration File for information aboutthe configuration file(s) required to run C applications.

Required Permissions

On Windows 7 and Windows Server 2008, you need to run your protected application asAdministrator.

6.2. Integration StepsThis sections provides steps on how to integrate Cloud Run-time APIs in your application.

6.2.1. Integrating Cloud Run-time APIs (Java) 213

6.2.2. Integrating Cloud Run-time APIs (.NET) 214

6.2.3. Integrating Cloud Run-time APIs (C) 214

6.2.1. Integrating Cloud Run-time APIs (Java)

1. Modify application class path to include client configuration file for Java, cache.ccf, ErrorCodes_en.properties, and the following jar files:

n SentinelCloudRuntime-<version>.jarn SaaSCommon.jarn SaaSxStream.jarn bcprov-jdk16-145.jarn commons-collections.jarn commons-logging-1.1.jarn concurrent.jarn dom4j-1.6.1.jarn jcs-1.3.jarn junit-3.8.1.jarn log4j-1.2.15.jarn quartz-all-1.7.3.jarn slf4j-api-1.5.8.jarn slf4j-log4j12-1.5.8.jarn xlightweb-2.13.2-jar-with-dependencies.jarn xpp3_min-1.1.4c.jar

2. Modify Client Configuration File to perform the required configuration settings. The name andlocation of the configuration file are specified in the section Name and Location of the ClientConfiguration File. The settings that you need to configure for cloud and on-premisedeployments are:

o YPSAddress

o DeploymentType

o ClientAlias

o SecretKey

o SecretKeyId

o VendorID

3. For On-premise applications, you will need to set the following additional properties:

o UsagePath

o UserInfoCache

4. For On-premise applications, copy SentinelCloudRuntime_P.dll (32-bit) orSentinelCloudRuntime_P_x64.dll (64-bit), at:

o C:\WINDOWS\system32

o a custom location and add the location in the Path environment variable.

5. Insert appropriate run-time API calls in the application. The decision of which API calls to insertand where, depends on your authorization strategy. Refer to Chapter 5: Sample Code of CloudRun-time APIs.



6.2.2. Integrating Cloud Run-time APIs (.NET)

1. Add reference of SentinelCloudRuntime.dll, log4net.dll,Microsoft.Practices.En-terpriseLibrary.Common.dll, Microsoft.Practices.EnterpriseLibrary.Caching.dll , Boun-cyCastle.Crypto.dll, Microsoft.Practices.ObjectBuilder.dll., Quartz.dll , Common.logging.dll,and Quartz.xml.

2. Copy all the sections of the client configuration file to your application configuration file, andupdate the elements given below. For details of the configuration file, see Name and Locationof the Client Configuration File.

n YPSAddress

n DeploymentType

n ClientAlias

n SecretKey

n SecretKeyId

n VendorID


o UsagePath

o UserInfoCache

For on-premise applications, if you want to enable the logging, then the user accountthat executes the licensed application must have access permissions for the file logginglocation mentioned in the LogFilePath property.

4. Insert appropriate run-time API calls in the application. The decision of which API calls to insertand where, depends on your authorization strategy.Refer to Chapter 5: Sample Code of CloudRun-time APIs.

6.2.3. Integrating Cloud Run-time APIs (C)

To integrate Cloud Run-time APIs in your source code:

1. Statically link the libraries as described below:

WindowsFor 32-bit (Debug Mode and Release Mode)

o Libraries to be linked: liblogger.lib, genx.lib, libexpatMT.lib, Iphlpapi.lib, libcurl.lib,libeay32MT.lib, ssleay32MT.lib, scrruntime.lib, scrdserializer.lib, libhasp_windows.lib,scrserializer.lib, ws2_32.lib, winmm.lib, wldap32.lib, wininet.lib, wsock32.lib, rpcrt4.lib,Ws2_32.lib, andWtsapi32.lib

o Libraries to be ignored: NoneFor 64-bit (Release Mode)

o Libraries to be linked: liblogger.lib, genx.lib, libexpatMT.lib, Iphlpapi.lib, libcurl.lib,libeay32.lib, ssleay32.lib, scrruntime_x64.lib, libhasp_windows_x64.lib, scrdserializer_x64.lib, scrserializer_x64.lib, ws2_32.lib, winmm.lib, wldap32.lib, wininet.lib,wsock32.lib, rpcrt4.lib, Ws2_32.lib, crypt32.lib, andWtsapi32.lib

o Libraries to be ignored: NoneFor 64-bit (Debug Mode)

o Libraries to be linked: liblogger.lib, genx.lib, libexpatMT.lib, Iphlpapi.lib, libcurl.lib,libeay32.lib, ssleay32.lib, scrruntime_x64.lib, libhasp_windows_x64.lib, scrdserializer_x64.lib, scrserializer_x64.lib, ws2_32.lib, winmm.lib, wldap32.lib, wininet.lib,wsock32.lib, rpcrt4.lib, Ws2_32.lib, msvcrt.lib, crypt32.lib, andWtsapi32.lib

o Libraries to be ignored: libcmt.lib and libcmtd.lib

LinuxFor 32-bit

o Libraries to be linked: libscrruntime.a, libscrdserializer.a, libscrserializer.a,liblogger.a, libgenx.a, libexpat.a, libcurl.a, libssl.a, libcrypto.a, rt, uuid, pthread ,libhasp_linux.a

o Libraries to be ignored: NoneFor 64-bit

o Libraries to be linked: libscrruntime_x64.a, libscrdserializer_x64.a, libscrserializer_x64.a, liblogger.a, libgenx.a, libexpat.a, libcurl.a, libssl.a, libcrypto.a, rt, uuid,pthread, libhasp_linux_x86_x64.a

o Libraries to be ignored: None

2. Include the run-time header files - cloudruntime.h and licenseclient.h.

3. Place the configuration file at the appropriate location. For name and location of configurationfile, refer the section Name and Location of the Client Configuration File.

4. Update the following properties in the configuration file.

o YPSAddress

o DeploymentType



o ClientAlias

o CAbundle

You can configure other settings as required. For details of configuration settings, see AppendixA: Client Configuration File.


o UsagePath

o UserInfoCache

6. Insert appropriate run-time API calls in the application. The decision of which API calls to insertand where, depends on your authorization strategy. Refer to Chapter 5: Sample Code of CloudRun-time APIs.

6.3. Best PracticesThis section discusses some of the best practices to assist you in a smooth and efficientimplementation of Cloud Run-time APIs.

6.3.1. Plan an Authorization Strategy

Analyze your licensing requirements and carefully design a strategy for authorization. The strategyhelps you decide suitable places in the code to insert the licensing calls, which will drive the entirefunctionality of your application. For example, a suitably placed combination of the login and logoutcalls will help you calculate the usage for a user.

6.3.2. Keep an Optimal Cache Size

Cache helps to improve overall performance but it consumes memory. To balance performance andmemory, keep an optimal number of values in cache. For example, if not using cache at all do thefollowing settings:

n For Java - Disable the cache by setting the number of records to be stored as zero.

n For .NET - Disable the cache by setting the ClientLicenseCache to “false".

n For C - Disable the cache by setting the ClientLicenseCache to “false".

This way all the requests will be processed by authorization server. But, we recommend keeping cacheenabled for enhanced user experience.

For more details about caching, see Section Appendix E: Caching (Cloud Deployment).

6.3.3. Set Optimal Time to Transfer Usage Logs

Cloud Run-time transfers the usage logs to Cloud Connect after a specific period defined in the clientconfiguration file. This value should be optimal. Lesser time interval degrades performance and moretime interval causes accumulation of usage logs, which constantly consumes critical memoryresources.

Appendix A:Client Configuration File

The Cloud Run-time reads its configuration settings from an XML-based configuration file during initialization.The configuration file should be stored in UTF-8 format.

n For a comprehensive list of the properties, see the Section List of Configuration Properties.

n For details about each property, see Configuration Properties Details.

n For knowing about the location and name of the configuration file, see Name and Location of the ClientConfiguration File.

n For details about the Run-time properties that you must configure, see the integration steps for therelated interface - Java, .NET, and C.

There are certain additional configuration properties, such as InMemoryUsageCount, which you can set by usingthe acquireLicenseClient API.

A.1. List of Configuration PropertiesHere is a comprehensive list of all the available configuration properties.

Category PropertyChangeRequired

DeploymentType

Run-time Source

DirectoryServices

YPSAddress Mandatory Cloud or On-premise

C,.NET,Java E-mailfromSafeNet

DirectoryServices

NodeDescription Optional Cloud or On-premise

C,.NET,Java Vendor

DirectoryServices

YPSRegister Not to bechanged

Cloud or On-premise

C,.NET,Java SafeNet

DirectoryServices

YPSSupportNode Not to bechanged

Cloud or On-premise

C,.NET,Java SafeNet

DirectoryServices

YPSHeartBeat Not to bechanged

Cloud or On-premise

C,.NET,Java SafeNet

DirectoryServices

YPSDeregister Not to bechanged

Cloud or On-premise

C,.NET,Java SafeNet

General Deployment Type Optional Cloud or On-premise

C,.NET,Java Vendor

A

218 Appendix A: Client Configuration File


DeploymentType

Run-time Source

General UsagePath Optional On-premise C,.NET,Java Vendor

General UserInfoCache Optional On-premise C,.NET,Java Vendor

General PeriodicJobUpdateTime Optional Cloud Java Vendor

Proxy ProxyConnect Optional Cloud or On-premise*

C Vendor

Proxy ProxyHost Optional Cloud or On-premise*

C Vendor

Proxy ProxyPort Optional Cloud or On-premise*

C Vendor

Proxy AutomaticProxyConfigurationUrl Optional Cloud or On-premise*

C Vendor

Proxy ProxyUserName Optional Cloud or On-premise*

C Vendor

Proxy ProxyPassword Optional Cloud or On-premise*

C Vendor

Logging Logging Optional Cloud or On-premise**

C,.NET,Java Vendor

Logging LogLevel Optional Cloud or On-premise**

C,.NET,Java Vendor

Logging LogFilePath Optional Cloud or On-premise**

C,.NET,Java Vendor

Logging LogFileMode Optional Cloud or On-premise**

C,.NET,Java Vendor

Advance VendorInfoLength Not to bechanged

Cloud or On-premise

C,.NET,Java SafeNet

Advance GCSInterval Not to bechanged

Cloud or On-premise

C,.NET,Java SafeNet

Advance WorstTimeOutMultiplier Not to bechanged

Cloud or On-premise

C,.NET,Java SafeNet

Advance Compression Not to bechanged

Cloud or On-premise

C,.NET,Java SafeNet

Advance MaxQueueSize Not to bechanged

Cloud or On-premise

C,.NET,Java SafeNet

Advance EnabledQueuedCommunication Not to bechanged

Cloud or On-premise

C,.NET,Java SafeNet

Advance JobBatchSize Not to bechanged

Cloud or On-premise

C,.NET,Java SafeNet

Advance ClientLicenseCache Not to bechanged

Cloud or On-premise

C,.NET,Java SafeNet


DeploymentType

Run-time Source

Security ClientAlias Mandatory Cloud or On-premise

C,.NET,Java E-mailfromSafeNet

Security VendorID Mandatory Cloud .NET,Java E-mailfromSafeNet

Security SecretKeyId Mandatory Cloud .NET,Java E-mailfromSafeNet

Security SecretKey Mandatory Cloud .NET,Java E-mailfromSafeNet

Security CAbundle Mandatory Cloud or On-premise

C Vendor

CloudConnect

ServerConnectionTimeout Optional Cloud or On-premise

C,.NET,Java Vendor

CloudConnect

ServerConnectionRetryCount Not to bechanged

Cloud or On-premise

C,.NET,Java SafeNet

.NETSpecific -Proxy

proxyaddress Optional Cloud .NET Vendor

.NETSpecific-Logging

Log4net –- level Optional Cloud .NET Vendor


Log4net –maximumFileSize Optional Cloud .NET Vendor


Log4net – logging location Optional Cloud .NET Vendor

.NETSpecific-Caching

maximumElementsInCacheBeforeScavenging Not to bechanged

Cloud .NET SafeNet


expirationPollFrequencyInSeconds Not to bechanged

Cloud .NET SafeNet


numberToRemoveWhenScavenging Not to bechanged

Cloud .NET SafeNet

*NOTE: Applicable to C, .NET and Java Run-times if Deployment Type is On-premise.

A.1. List of Configuration Properties 219


**NOTE: Applicable to C Run-time if Deployment Type is Cloud or On-premise. Applicable to Java and .NET Run-times if Deployment Type is On-premise.

For on-premise DeploymentType of .NET and Java Run-times, you need to set configuration propertiesmentioned for C Run-time.

A.2. Configuration Properties DetailsThe configuration properties are described below:

A.2.1. Directory Server Configuration

Property Name - Description - Sample

YPSAddress**

Address of the Cloud Directory Services.Sample for Java. .NET, and C -<add key="YPSAddress"value="https://localhost:443/YPServer" />

NodeDescription**

Node description.Sample for Java, .NET, and C -<add key="nodeDescription" value=" Client node forsample application" />

YPSRegister

Address of the Cloud Directory Services registration request.Sample for Java. .NET, and C -<add key="YPSRegister" value="/registerNode.form" />

YPSSupportNode

Address of the Cloud Directory Services support node request.Sample for Java. .NET, and C -<add key="YPSSupportNode" value="/supportNode.form"/>

YPSHeartBeat

Address of the Cloud Directory Services heartbeat request.Sample for Java. .NET, and C -add key="YPSHeartBeat"value="/refreshRegistration.form" />

YPSDeregister

Address of the Cloud Directory Services de-registration request.Sample for Java. .NET, and C -<add key="YPSDeregister" value="/deregisterNode.form"/>

A.2.2. General Configuration


Deployment Type**


Specifies the type of licensing you want to incorporate. Its value can be either OnPremise or Cloud.Sample for Java, .NET, and C -<add key="DeploymentType" value="Cloud"/>

UsagePath**

The path of the persistent usage log file. This property is applicable for On-premise applications. Please notethe following:

n The specified path should not contain any file with the extension “.$$$”.n The user account used to execute the licensed application must have write permission for the specified

path.n The directory mentioned in path should not contain the ‘&’ character.

Sample for Java, .NET, and C -<add key="UsagePath" value ="C:\usage\" />

This property does not support internationalized characters.

UserInfoCache

Specifies the location where local cache for users is created.Sample for Java, .NET, and C -<add key="UserInfoCache" value ="C:\usage\" />

The location for the UserInfoCache property should be same for multiple applications or multipleinstances of an application running on a system.

PeriodicJobUpdateTime**

Period in seconds after which the quartz scheduler processes the periodic job requests. For Cloud applications,the scheduler sends usage logs for Run-time. This property is applicable only for Cloud applications.Sample for Java, .NET, and C -<add key="PeriodicJobUpdateTime" value="600" />

In the case of on-premise licensing, Run-time transfers usage data to Cloud Connect after State Synctime, which is set in Cloud Connect.

A.2.3. Proxy Settings


ProxyConnect

Proxy connection on/off flag. The possible values are:

n 0 – Proxy is disabled.n 1 – Auto Proxy is enabled.

For Windows, the DHCP and DNS WPAD discovery methods are used. For Linux, only the DNS discoverymethod is used.TheWPAD-enabled run-time first uses DHCP to find a server, and if the desired information is notobtained, DNS is used.If thewpad.dat file is not found, the RT_ERR_COULDNT_DETECT_PROXY error is returned.

n 2-Manual Proxy is enabled.In this mode, the proxy details specified in ProxyHost and ProxyPort properties are used to find a proxyserver.

A.2. Configuration Properties Details 221



In the Cloud mode of Java, only the options 0 and 2 are available that indicate if the proxy is disabled orenabled respectively.

Sample for C and Java -<add key="ProxyConnect" value ="0" />

ProxyHost

Adds the proxy host.Sample for C and Java -<add key="ProxyHost" value ="localhost" />

ProxyPort

Adds the proxy port.Sample for C and Java -<add key="ProxyPort" value ="8080" />

AutomaticProxyConfigurationUrl

The location of the auto-proxy configuration (.pac) file which is used for proxy detection. Set this property whenAuto Proxymode is enabled. If this property is not set, then WPADmethod is used by default for proxydetection.Sample for C -<add key="AutomaticProxyConfigurationUrl"value="http://<ProxyScriptHostUrl>/proxy.pac" />

ProxyUserName

Name used for proxy authentication. Specify this if you want the proxy authentication to be done bycredentials other than the system credentials.Sample for C and Java -<add key="ProxyUserName" value ="userName"

ProxyPassword

Password used for proxy authentication. Specify this if you want the proxy authentication to be done bycredentials other than the system credentials.Sample for C and Java -<add key="ProxyPassword" value ="password" />

A.2.4. Logging Settings


Logging

Turn On/Off the creation of log file (for C interface). 1 specifies On, and 0 Specifies Off.Sample for C -<add key="Logging" value ="1" />

LogLevel

Customize logging level.

n Possible logging levels are: 1 – Trace(lowest priority), 2 – Debug, 3 – Information, 4 –Warning, 5 – Error, 6– Fatal (highest priority)

n Logs will be generated for levels whose priority is higher or equal to the level specified in LogLevelproperty.

n If log level specified is out of range, then logging will be off.n The default log level is 4 -Warn.

Sample for C - <add key="LogLevel" value ="4" />


LogFilePath

The path of the Cloud Run-time log file (for C interface). The same path is used in Java and .NET on-premiseapplications.Sample for C -<add key="LogFilePath" value ="Runtime.log" />


LogFileMode

Used to either create a new log file or use the existing file (for C interface). 0 is for new log file, and 1 is forappending to existing log file.Sample for C -<add key="LogFileMode" value ="1" />

A.2.5. Advanced Properties

These are read-only properties and should not be changed without consulting SafeNet.


VendorInfoLength**

Themaximum number of bytes to be contained in the vendor information.Sample for Java, .NET, and C - <add key="VendorInfoLength" value="255" />

GCSInterval**

Time in seconds to schedule garbage collector shrinker. This property is applicable only for Cloud applications.Sample for Java, .NET, and C -<add key="GCSInterval" value ="600" />

WorstTimeOutMultiplier

Multiplies the time to live of a record in cache. This property is applicable only for Cloud applications.Sample for Java, .NET, and C -<add key="WorstTimeOutMultiplier" value ="10" />

Compression

Flag to enable\disable compression. This property is applicable only for Cloud applications.Sample for Java -<add key="Compression" value ="false" />

MaxQueueSize

Queuewhich can contain themaximum number of objects in memory. Set -1 for an unbounded queue. Thisproperty is applicable only for Cloud applications.Sample for .NET -<add key="MaxQueueSize" value="10000" />

EnabledQueuedCommunication

Sample for C,.NET,Java - <add key="EnabledQueuedCommunication" value ="false" />

JobBatchSize

The number of requests which can be combined together for sending to the Cloud Connect in a single HTTPrequest message. This property is applicable only for Cloud applications.Sample for .NET - <add key="JobBatchSize" value ="10" />




ClientLicenseCache**

Flag to enable or disable license information caching. This property is applicable only for Cloud applications.Sample for .NET and C -<add key="ClientLicenseCache" value="true" />

A.2.6. Security Configuration


ClientAlias**

The vendor name provided in the vendor registration request file.Sample for Java, .NET, and C -<add key="ClientAlias" value="isv" />

VendorID

The unique ID assigned to a software vendor.Sample for Java and .NET -<add key="VendorId" value="a8e06c3" />

SecretKeyId

ID of the secret key.Sample for Java and .NET -<add key="SecretKeyId" value="SecretKeyId" />

SecretKey

The secret key used for authenticating client requests. Each software vendor is provided a secret key bySafeNet.Sample for Java and .NET-<add key="SecretKey" value="SecretKey" />

CAbundle

The path of the CA bundle, which refers to the certificate store that C runtime uses for server certificateverification. You can download CA certificate bundle from http://curl.haxx.se/ca/cacert.pem.Sample for C -<add key="CAbundle" value=".\cacert.pem" />

A.2.7. Cloud Connect Configuration


ServerConnectionTimeout**

Time interval (in seconds) after which the Cloud Run-time tries to connect with the Cloud Connect.Sample for Java, .NET, and C -<add key="ServerConnectionTimeout" value="300" />

ServerConnectionRetryCount**

The number of attempts made by the Cloud Run-time to connect with the Cloud Connect.Sample for Java, .NET, and C -<add key="ServerConnectionRetryCount" value="5" />

A.2.8. .NET Specific Configurations


proxyaddress

http://curl.haxx.se/ca/cacert.pem


Address and port of proxy host.Sample for .NET -<proxy proxyaddress="http://localhost:8080"usesystemdefault="False" />

CachingConfiguration - expirationPollFrequencyInSeconds

The interval after which cache items are checked for expiration. This property is applicable only for Cloudapplications.Sample for .NET-expirationPollFrequencyInSeconds=”60”

CachingConfiguration - maximumElementsInCacheBeforeScavenging

Sets themaximum number of elements in cache before scavenging. Change the value of“maximumElementsInCacheBeforeScavenging”. This property is applicable only for Cloud applications.Sample for .NET -maximumElementsInCacheBeforeScavenging=”1000”

CachingConfiguration - numberToRemoveWhenScavenging

Sets the numbers of items that will be removed from cache when its size reaches to maximum. This property isapplicable only for Cloud applications.Sample for .NET -numberToRemoveWhenScavenging=”10”

Log4net - level **

Logging level for the Cloud Run-time. This property is applicable only for Cloud applications.The following levels are defined in order of increasing priority:

n ALL – All themessages for log level DEBUG, INFO, WARN, ERROR, and FATAL are logged.n DEBUG – Debug information is logged, along with INFO, WARN, ERROR, and FATAL log messages.n INFO – Tracing information is logged, along with WARN, ERROR, and FATAL log messages.n WARN –Warning messages are logged, along with ERROR and FATAL log messages.n ERROR – General error messages are logged, along with FATAL log messages.n FATAL – Only fatal errors are logged.n OFF - No logs aremaintained.

Sample for .NET -<level value="INFO" />

Log4net – logging location **

The location of the Cloud Run-time log file. Change the value of “File”. This property is applicable only for Cloudapplications.Sample for .NET -<param name="File" value="RunTime.log" />


Log4net – maximumFileSize

The size of the Cloud Run-time log file. Change the value of “maximumFileSize”. This property is applicable onlyfor Cloud applications.Sample for .NET -<maximumFileSize value="1MB" />

** Properties frequently configured by the software publisher (compared to the remaining ones).



A.3. Name and Location of the Client Configuration FileA common XML-based configuration file is used by Java, .NET, and C Run-time. The name of the configuration fileis SentinelCloudRuntime.properties. Its location in different language interfaces is given below:

Interface Location

Java Place at the class path of your application.For on-premise applications, you also need to specify this location in the SFNT_SCR_CONFIG_FILEPATH environment variable. Note that the on-premise application will not work if theconfiguration file is placed within a jar file at class path. See Defining a Custom Path forConfiguration File for details.

.NET Copy the properties to your application's configuration file.For on-premise applications, you also need to set the configuration file path in the SFNT_SCR_CONFIG_FILEPATH environment variable.See Defining a Custom Path for Configuration File fordetails.

C Place at one of the following locations:

n In the current execution directory.n In the working folder if you are using Microsoft Visual Studio.n At the custom path specified by the SFNT_SCR_CONFIG_FILEPATH environment variable.

See Defining a Custom Path for Configuration File for details.

A.3.1. Defining a Custom Path for Configuration File

You can place the SentinelCloudRuntime.properties client configuration file at a custom path of your choice, andspecify the path in the SFNT_SCR_CONFIG_FILEPATH environment variable. The use of environment variableallows you to define the configuration settings once for the protected applications stored at different locations.

Notes:

n In C interface, if the SFNT_SCR_CONFIG_FILEPATH environment variable is not set or set to an incorrectpath, the run-time searches the configuration file in the current execution directory.

n The user account used to execute the licensed application must have access permissions for the file pathmentioned in the SFNT_SCR_CONFIG_FILEPATH environment variable.

A.4. Proxy ConfigurationProxy Configuration Methods

You can configure proxy by using any of the following methods:

n Manual: Manually specify the proxy server host and port in the client configuration file.

n Automatic: Proxy settings are automatically detected. There are two alternatives for automatic proxydetection:

o WPAD (Web Proxy Autodiscovery Protocol): In this case, proxy detection can be done by usingeither DNS or DHCP. DHCP has a higher priority than DNS.

o PAC (Proxy Auto-configuration): In this case, the location of proxy script file should be specifiedin the configuration file.

By default in Automatic proxy mode, WPAD is used for proxy detection.

To use proxy PAC script, you need to specify the location of proxy script file in the configurationfile.

Proxy Authentication

Authentication can be enabled or disabled at proxy server. When enabled, proxy server must be authenticatedafter it has been detected. Authentication can be performed either by using Windows credentials or manually byusing user name and password. On Linux, proxy authentication using system credentials is not supported.

About Automatic Proxy Detection Support

This section provides information on automatic proxy detection methods supported by different deploymenttypes.

Cloud DeploymentType

Windows:All proxy methods supported for all interfaces (Java, .NET, C)

n C: All supportedn Java: Not supportedn .NET: System settings are picked automatically. For details ofmanual settings,

refer to: http://msdn.microsoft.com/en-US/library/sa91de1e%28v=vs.80%29.aspx

Linux:All supported (except WPAD-DHCP)

Proxy authentication using system credentials is not supported.

On-premiseDeployment Type

Windows:

n C: All supportedn Java: All supportedn .NET: All supported

Linux:

n C: All supported (except WPAD-DHCP)n Java: All supported (except WPAD-DHCP)

Proxy authentication using system credentials is not supported.

A.4. Proxy Configuration 227

http://msdn.microsoft.com/en-US/library/sa91de1e(v=vs.80).aspx

http://msdn.microsoft.com/en-US/library/sa91de1e(v=vs.80).aspx


Proxy Configuration Settings

You can configure proxy setting by using the configuration file. See section Proxy Settings for details.

Appendix B:Troubleshooting

This section describes solutions to common problems you may encounter when using the Cloud Run-time APIs.

B.1. No Server Mapped to the Given Vendor ID (1001)Applicability: C, Java, and .NET - All Deployments

This RT_ERR_NO_AUTH_SERVER error occurs when no instance of the Cloud Connect, corresponding to the givenvendor ID, is up. To resolve this condition, ensure that the Cloud Connect is up and running and then initializeRun-time library again (by calling the acquireLicenseClient API).

B.2. Unable to Initialize Run-time Library (1003)Applicability: C - All Deployments, Java and .NET - On-premise Deployments

This error occurs when the user account that executes the licensed application does not have access permissionsfor the file logging location mentioned in the LogFilePath property. Provide the required permissions to the useraccount.

B.3. Internal Error or Internal System Error (1009)Applicability: C - All Deployments, Java and .NET - On-premise Deployments

Turn on the logging to identify the exact cause of error. You can turn on/off the logging from the clientconfiguration file.

B.4. Error RT_ERR_INVALID_COOKIE (1016)Applicability: C, Java, and .NET - On-premise Deployments

The possible reasons of this error are:

n The cookie string is incorrect.

n The cookie is no longer valid due to expiration of authenticated session.

To resolve this error:

B

230 Appendix B: Troubleshooting

n Ensure that the cookie passed is same as returned by the getIdentity API for this user.

n Call getIdentity API with the cloud action.

B.5. Error in Detaching Licenses by Using the transfer API (1021)Applicability: C, Java, and .NET - On-premise Deployments

The error RT_ERR_NO_EID_REGISTERED occurs if an entitlement is not registered with a machine.

To resolve this error, ensure that entitlement ID (EID) is registered with themachine.The registration can be doneby using EMS web service (Add Entitlement Fingerprint).

B.6. Abnormal Application Termination on Linux (1025)Applicability: C - All Deployments, Java - On-premise Deployments on L inux

When an application using Run-time library for Linux crashes, the application may not respond the next time youexecute it. This may happen when locks maintained by the Run-time are not released.

To resolve this, remove the locks (if they exist) by using the following command:

rm -rf /dev/shm/sem.SFNTSCR*

B.7. Connection to the Cloud Directory Services Failed (2001)Applicability: Java, .NET, C - Cloud Deployment

This error occurs in the following cases:

n Cloud Directory Services server is down

n The address of the Cloud Directory Services server in the configuration file is incorrect.

To resolve the later condition, try the following steps:

1. Open the configuration file.

2. Search for the YPSAddress property name.

3. Specify correct address in this property value and then initialize the Cloud Run-time again by restartingyour licensed application on the web.

B.8. Communication Error (2001 to 2012)Applicability: C - All Deployments, Java and .NET - On-premise Deployments

The communication errors may occur in following situations:

1. Cloud Connect and Directory Services return none for the request sent by Cloud Run-time.

2. A communication error occurs, such as data post error or SSL certificate problem.

3. Connection to the Directory Services or Cloud Connect fails.

4. Directory Services server is down.

5. The address of Directory Services server in the configuration file is incorrect.

6. The proxy settings are either not provided or specified incorrectly in the configuration file.

Try the following steps to resolve this error:

1. Turn on the logging to identify the exact cause of error. You can turn on/off the logging from the clientconfiguration file.

2. Search for the YPSAddress property name in the configuration file, and specify correct address in this prop-erty value. Initialize Cloud Run-time again by restarting your licensed application on the web.

3. Set the proxy settings (such as, ProxyConnect, ProxyHost, and ProxyPort) correctly in the client con-figuration file. See section Proxy Settings for configuration details.

B.9. Error RT_ERR_INVALID_AUTHENTICATION (2011)Applicability: C, Java and .NET - All Deployments

This error occurs when authentication fails due to any of the following reasons:

n Mismatch in Secret Key

n Mismatch in Secret Key ID

n Incorrect Vendor ID

To resolve this error, open the configuration file and ensure that correct values are specified in the followingproperties:

o SecretKey

o SecretKeyId

o VendorID

B.10. Problem in Loading Configuration File (2501)Applicability: C - All Deployments, Java and .NET - On-premise Deployments

The error RT_ERR_IN_CONF_FILE_LOAD occurs if Run-time configuration file is not placed at the correct location.

To resolve this error:

n If environment variable SFNT_SCR_CONFIG_FILEPATH is set , configuration file should be placed at thatlocation.

B.9. Error RT_ERR_INVALID_AUTHENTICATION (2011) 231

232 Appendix B: Troubleshooting

n Place the configuration file at the location where application's executable is stored.

n If you are deploying .NET on-premise Run-time over IIS, place the configuration file in the executionfolder of the web application, which depends on the OS and IIS version.

B.11. Error RT_ERR_NO_AUTH_SESSION (-14007)Applicability: C, Java, and .NET - On-premise Deployments

The error indicates that the authentication session has expired. To resolve this error, call the getIdentity API withthe cloud action. This will recreate the authentication session for the user.

B.12. Error RT_ERR_INVALID_FINGERPRINT (-14008)Applicability: C, Java, and .NET - On-premise Deployments

This error indicates that either themachine is not provisioned or provisioned incorrectly. You need to registerthe fingerprint of customer's machine to resolve this error. For information on Machine Registration, refer toEMS Web Services Guide.

B.13. Error RT_ERR_INVALID_CUSTOM_CRITERIA (-14020 )Applicability: C, Java, and .NET - On-premise Deployments

This error indicates that either themachine is not provisioned or provisioned incorrectly. You need to registerthe host name (called Custom Fingerprint) of customer's machine to resolve this error. For information onMachine Registration, refer to EMS Web Services Guide.

B.14. Problem in integrating Sentinel Cloud due to .NET VersionApplicability: .NET - Cloud Deployment

This is a generic issue which occurs due to different versions of same .NET assembly being used by third partyframeworks. For example, the third party framework is using log4net or quartz with different version than yours.This issue can be resolved by providing information of different versions of assembly in theweb.config file.

Given below are the steps that have been tested with quartz and .NET:

1. Create two folders, one for each version of DLL. Place DLLs into corresponding folders and then add themto project (do not use Add Reference). For example:

o Quartzv1.0.3.2/Quartz.dll

o Quartzv2.0.0.0/Quartz.dll

2. Set the copy to output directory property to copy always so that it is automatically copied to the outputfolder when you build.

3. Modify app.config to provide assembly name, public token, version, and path. After modification theweb.config file will look like:

<configuration>

<runtime>

<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">

<dependentAssembly>

<assemblyIdentity name="Quartz" publicKeyToken="f6b8c98a402cc8a4" />

<codeBase version="1.0.3.2" href="Quartzv1.0.3.2\Quartz.dll" />

</dependentAssembly>

<dependentAssembly>

<assemblyIdentity name=" Quartz " publicKeyToken=" f6b8c98a402cc8a4" />

<codeBase version="2.1.2.400" href="Quartzv2.1.2.400\Quartz.dll" />

</dependentAssembly>

</assemblyBinding>

</runtime>

</configuration>

After abovemodifications, the application should run properly.

Reference link: http://stackoverflow.com/questions/3158928/referencing-2-differents-versions-of-log4net-in-the-same-solution.

B.14. Problem in integrating Sentinel Cloud due to .NET Version 233

http://stackoverflow.com/questions/3158928/referencing-2-differents-versions-of-log4net-in-the-same-solution

http://stackoverflow.com/questions/3158928/referencing-2-differents-versions-of-log4net-in-the-same-solution

Appendix C:Error Codes

This section lists the common errors returned by Sentinel Cloud Run-time.

C.1. Error Codes (Java) 236

C.2. Error Codes (.NET) 238

C.3. Error Codes (C) 240

C.4. Obsolete Error Codes 244

C

236 Appendix C: Error Codes

C.1. Error Codes (Java)Error Code Error Description

Generic Errors

RT_ERR_NO_AUTH_SERVER 1001 No authorization server mapped to given vendor IDSee Troubleshooting for details.

RT_ERR_INVALID_PARAMETER 1002 Value of input parameter is wrong

RT_ERR_CRT_NOT_INITIALIZED 1003 Unable to initialize runtime librarySee Troubleshooting for details.

RT_ERR_IN_CERT_LOAD 1004 Error while loading certificates

RT_ERR_IN_LICENSE_GET 1005 Invalid license attributes returned by server

RT_ERR_IN_CRT_CLEANUP 1006 Unable to de-initialize runtime library

RT_ERR_IN_LOCKING 1008 Problem with accessing shared data

RT_INTERNAL_ERR 1009 Internal error has occurredSee Troubleshooting for details.

RT_ERR_INTERNAL_SYS 1010 Internal system error e.g. time calculation error ,error in encoding

RT_ERR_INVALID_CUSTOMER 1020 Customer is invalid

RT_ERR_NO_EID_REGISTERED 1021 EID is not registered for customer

RT_ERR_MAX_STATION_COUNT_REACHED 1022 Max station count reached for EID

RT_ERR_NO_LICENSE_IN_DETACHED_STORE 1023 No license present in detached store

RT_ERR_OPERATION_NOT_SUPPORTED 1024 Invalid use of API

RT_ERR_CLR_OLD_LOCK 1025 Clear locks created by previous application that didnot exit gracefully.See Troubleshooting for details.

RT_ERR_LICENSE_EXPIRED_NO_CONNECTIVITY

1026 Local license has expired and also there is noconnectivity to Sentinel Cloud Connect

RT_ERR_NO_LICENSE_NO_CONNECTIVITY 1027 Local license is not present and also there is noconnectivity to Sentinel Cloud Connect

RT_ERR_INVALID_LICENSE_STATE 1028 License State supplied in transfer API to get remotedetach license and apply license is not valid

RT_ERR_DUPLICATE_LICENSE_STATE 1029 License State supplied in transfer API to applylicense is already installed

RT_ERR_IN_COMMUNICATION 2001 Failed to communicateSee Troubleshooting for details.

RT_ERR_INVALID_AUTHENTICATION 2011 Authentication Failed.Refer to Error RT_ERR_INVALID_AUTHENTICATION(2011) for details.

Error Code Error Description

Configuration Errors

RT_ERR_IN_CONF_FILE_LOAD 2501 Problem in configuration file reading.See Troubleshooting for details.

RT_ERR_INVALID_SERVER_CONN_TIMEOUT 2502 Invalid value of “ServerConnectionTimeout”

RT_ERR_INVALID_SERVER_RETRY_COUNT 2503 Invalid value of “ServerConnectionRetryCount”

RT_ERR_INVALID_YPS_ADDRESS 2504 Invalid YPS address

RT_ERR_INVALID_REG_NODE_URL 2505 Invalid URL address

RT_ERR_INVALID_DEREG_NODE_URL 2506 Invalid URL address

RT_ERR_INVALID_SUPP_NODE_URL 2507 Invalid URL address

RT_ERR_INVALID_HEART_BEAT_URL 2508 Invalid URL address

RT_ERR_INVALID_JOB_INTERVAL 2509 Invalid value of job interval

RT_ERR_INVALID_CLIENT_ALIAS 2511 Invalid value of client alias

RT_ERR_INVALID_NODE_DESCRIPTION 2512 Invalid Node Description

RT_ERR_INVALID_PROXY_ADDRESS 2513 Invalid Proxy Host

RT_ERR_INVALID_PROXY_PORT 2514 Invalid Proxy port

RT_ERR_INVALID_DEPLOYMENT_TYPE 2516 Invalid Deployment Type

RT_ERR_INVALID_PERIODIC_REFRESH_TIME 2517 Invalid Periodic Refresh Time

RT_ERR_INVALID_GCS_INTERVEL 2518 Invalid GCS Interval (Reserved for Java)

RT_ERR_INVALID_VENDERINFO_LEN 2519 Invalid VendorInfoLength (Reserved for Java)

RT_ERR_INVALID_WORST_TIME_MULTIPLIER 2520 Invalid worstTimeOutMultiplier (Reserved for Java)

RT_ERR_INVALID_LOG_FILEPATH 2522 Invalid log file path

RT_ERR_INVALID_USAGE_LOG_PATH 2529 Invalid Usage log file path (in the case of on-premiseapplications)

RT_ERR_INVALID_VENDOR_ID 2530 Vendor Code is null,empty, or exceeds themaximum allowed length (255 chars).

RT_ERR_INVALID_SECRET_KEY 2531 Secret Key is null,empty, or exceeds themaximumallowed length (255 chars).

RT_ERR_INVALID_SECRET_KEY_ID 2532 Secret Key ID is null,empty, or exceeds themaximum allowed length (255 chars).

Licensing Errors

RT_ERR_LICENSE_NOT_ACTIVATED - 10000 License is not activated

RT_ERR_LICENSE_IS_EXPIRED - 10001 License is expired

RT_ERR_LICENSE_IS_DISABLED - 10002 License is disabled

RT_ERR_LICENSE_ERROR - 10003 Unknown error thrown by license engine

RT_ERR_LICENSE_IS_REVOKED - 10004 License is revoked

RT_ERR_MAX_CONCU_LIMIT_REACHED - 10005 Maximum concurrent user limit reached

C.1. Error Codes (Java) 237



RT_ERR_LICENSE_COUNT_EXHAUSTED - 10006 License count exhausted

RT_ERR_IN_LICENCE_RELEASE - 10007 Problem in license release

RT_ERR_UNKNOWN_ERROR - 12000 Unknown error thrown by SCC

RT_ERR_INTERNAL_SCC - 12001 SCC internal error

RT_ERR_LICENSE_DOES_NOT_EXISTS - 14000 License does not exist

RT_ERR_INVALID_FEATURE_PARAMETER - 14001 Invalid parameter (Feature)

RT_ERR_CUSTOMER_PARAMETER - 14002 Invalid parameter (Customer)

RT_ERR_IDENTITY_PARAMETER - 14003 Invalid parameter (Identity)

RT_ERR_PARAMETER - 14004 Invalid parameter

RT_ERR_SESSION_TERMINATED -14005 Session terminated.

RT_ERR_CAPACITY_ATTRIBUTE_NOT_FOUND -14018 No license with capacity attribute found

RT_ERR_INVALID_CUSTOM_CRITERIA -14020 Invalid fingerprint custom criteria

RT_ERR_POLICY_DOES_NOT_ALLOW - 15000 Access denied to the requested feature

C.2. Error Codes (.NET)Error Code Error Description

Generic Errors



RT_ERR_CRT_NOT_INITIALIZED 1003 Unable to initialize runtime librarySee Troubleshooting for details.

RT_ERR_IN_CERT_LOAD 1004 Error while loading certificates


RT_ERR_IN_CRT_CLEANUP 1006 Unable to de-initialize runtime library



RT_ERR_INTERNAL_SYS 1010 Internal system error e.g. time calculation error ,error in encoding











RT_ERR_DUPLICATE_LICENSE_STATE 1029 License State supplied in transfer API to apply licenseis already installed


RT_ERR_INVALID_AUTHENTICATION 2011 Authentication Failed.Refer to Error RT_ERR_INVALID_AUTHENTICATION(2011) for details.


RT_ERR_IN_CONF_FILE_LOAD 2501 Problem in configuration file readingSee Troubleshooting for details.



















RT_ERR_INVALID_MAX_QUEUE_SIZE 2523 Invalid MaxQueueSize(Reserved for .NET)

C.2. Error Codes (.NET) 239



RT_ERR_INVALID_JOB_BATCH_SIZE 2524 Invalid JobBatchSize(Reserved for .NET)

RT_ERR_INVALID_VENDORID 2525 Invalid Vendor ID (Reserved for .NET)

RT_ERR_INVALID_CLIENT_LICENSE_CACHE 2526 Invalid ClientLicenseCache(Reserved for .NET)


RT_ERR_INVALID_VENDOR_ID 2530 Vendor Code is null,empty, or exceeds themaximum allowed length (255 chars).

RT_ERR_INVALID_SECRET_KEY 2531 Secret Key is null,empty, or exceeds themaximumallowed length (255 chars).

RT_ERR_INVALID_SECRET_KEY_ID 2532 Secret Key ID is null,empty, or exceeds themaximum allowed length (255 chars).

Licensing Errors

RT_ERR_LICENSE_NOT_ACTIVATED - 10000 License is not activated

RT_ERR_LICENSE_IS_EXPIRED - 10001 License is expired

RT_ERR_LICENSE_IS_DISABLED - 10002 License is disabled

RT_ERR_LICENSE_ERROR - 10003 Unknown error thrown by license engine

RT_ERR_LICENSE_IS_REVOKED - 10004 License is revoked

RT_ERR_MAX_CONCU_LIMIT_REACHED - 10005 Maximum concurrent user limit reached

RT_ERR_LICENSE_COUNT_EXHAUSTED - 10006 License count exhausted

RT_ERR_IN_LICENCE_RELEASE - 10007 Problem in license release

RT_ERR_UNKNOWN_ERROR - 12000 Unknown error thrown by Cloud Connect

RT_ERR_INTERNAL_SCC - 12001 Cloud Connect internal error

RT_ERR_LICENSE_DOES_NOT_EXISTS - 14000 License does not exist

RT_ERR_INVALID_FEATURE_PARAMETER - 14001 Invalid parameter (Feature)

RT_ERR_CUSTOMER_PARAMETER - 14002 Invalid parameter (Customer)

RT_ERR_IDENTITY_PARAMETER - 14003 Invalid parameter (Identity)

RT_ERR_PARAMETER - 14004 Invalid parameter



RT_ERR_INVALID_CUSTOM_CRITERIA -14020 Invalid fingerprint custom criteria

RT_ERR_POLICY_DOES_NOT_ALLOW - 15000 Access denied to the requested feature

C.3. Error Codes (C)Error Code Error Description

Generic Errors




RT_ERR_CRT_NOT_INITIALIZED 1003 Unable to initialize Run-time librarySee Troubleshooting for details.


RT_ERR_IN_CRT_CLEANUP 1006 Unable to de-initialize Run-time library

RT_ERR_IN_LICENCE_RELEASE 1007 Problem in license release



RT_ERR_INTERNAL_SYS 1010 Internal system error, example error in timecalculation or encoding






RT_ERR_NO_RESOURCE_AVAILABLE 1011 No resource available, examplemalloc failed

RT_ERR_IN_REGISTRATION 1012 Run-time registration failure

RT_ERR_IN_LICENSE_GEN 1013 Error in license generations

RT_ERR_GETTING_IDENTITY_INFO 1014 Error getting identity info

RT_ERR_INVALID_IDENTITY 1015 Identity is invalid

RT_ERR_INVALID_COOKIE 1016 Invalid cookie suppliedSee Troubleshooting for details.

RT_ERR_IN_TRANSFER 1017 Error in transferring licenses

RT_ERR_RESYNC_ALREADY_IN_PROGRESS 1018 Resync is already in progress

RT_ERR_AUTHENTICATION_IS_OFF 1019 Authentication is disabled


RT_ERR_NO_EID_REGISTERED 1021 EID is not registered for customerSee Troubleshooting for details.




RT_ERR_CLR_OLD_LOCK 1025 Clear locks created by previous application that didnot exit gracefully.




See Troubleshooting for details.





RT_ERR_DUPLICATE_LICENSE_STATE 1029 License State supplied in transfer API to apply licenseis already installed


RT_ERR_COULDNT_RESOLVE_PROXY 2002 The given proxy host could not be resolved.

RT_ERR_COULDNT_RESOLVE_HOST 2003 The given remote host was not resolved.

RT_ERR_OPERATION_TIMEDOUT 2004 The communication timeout timewas reached

RT_ERR_SSL_CONNECT_ERROR 2005 Error when connecting with SSL

RT_ERR_PEER_FAILED_VERIFICATION 2006 The remote server's SSL certificate is not correct.

RT_ERR_SSL_CERTPROBLEM 2007 Problem with the local certificate

RT_ERR_SSL_CACERT_BADFILE 2008 Problem with reading the SSL CA certificate

RT_ERR_SSL_CACERT 2009 Problem with the CA certificate

RT_ERR_COULDNT_DETECT_PROXY 2010 Not able to detect proxy in case of AutoProxy mode.

RT_ERR_INVALID_AUTHENTICATION 2011 Authentication Failed.Refer to How to resolve error RT_ERR_INVALID_AUTHENTICATION (2011)? for details.

RT_ERR_PUSH_USAGE_IN_SCC 2012 Error in processing usage


RT_ERR_IN_CONF_FILE_LOAD 2501 Problem in configuration file readingSee Troubleshooting for details.














RT_ERR_INVALID_REGISTRATION_WS_URL 2515 Invalid registration URL








RT_ERR_INVALID_VENDOR_ID 2530 Vendor Code is null, empty, or exceeds themaximum allowed length (255 chars).

RT_ERR_INVALID_SECRET_KEY 2531 Secret Key is null, empty, or exceeds themaximumallowed length (255 chars).

RT_ERR_INVALID_SECRET_KEY_ID 2532 Secret Key ID is null, empty, or exceeds themaximum allowed length (255 chars).

RT_ERR_INVALID_CA_BUNDLE 2533 Invalid value of CAbundle property

Licensing Errors

RT_ERR_LICENSE_NOT_ACTIVATED -10000 License is not activated

RT_ERR_LICENSE_IS_EXPIRED -10001 License is expired

RT_ERR_LICENSE_IS_DISABLED -10002 License is disabled

RT_ERR_LICENSE_ERROR -10003 Unknown error thrown by license engine

RT_ERR_LICENSE_IS_REVOKED -10004 License is revoked

RT_ERR_MAX_CONCU_LIMIT_REACHED -10005 Maximum concurrent user limit reached

RT_ERR_LICENSE_COUNT_EXHAUSTED -10006 License count exhausted

RT_ERR_UNKNOWN_ERROR -12000 Unknown error thrown by SCC

RT_ERR_INTERNAL_SCC -12001 SCC internal error

RT_ERR_LICENSE_DOES_NOT_EXISTS -14000 License does not exist

RT_ERR_INVALID_FEATURE_PARAMETER -14001 Invalid parameter (Feature)

RT_ERR_CUSTOMER_PARAMETER -14002 Invalid parameter (Customer)

RT_ERR_IDENTITY_PARAMETER -14003 Invalid parameter (Identity)

RT_ERR_PARAMETER -14004 Invalid parameter


RT_ERR_IN_USER_AUTHENTICATION -14006 Error verifying user credentials from authentication




system

RT_ERR_NO_AUTH_SESSION -14007 Cookie corresponding to authentication session hasexpiredSee Troubleshooting for details.

RT_ERR_INVALID_FINGERPRINT -14008 Fingerprint is not provisionedSee Troubleshooting for details.

RT_ERR_AUTH_PAY_LOAD_SIZE_EXCEEDS -14017 authPayLoad limit exceeds themaximum allowedvalue


RT_ERR_INVALID_CUSTOM_CRITERIA -14020 Invalid fingerprint custom criteriaSee Troubleshooting for details.

RT_ERR_POLICY_DOES_NOT_ALLOW -15000 Access denied to the requested feature

C.4. Obsolete Error CodesThis section contains a list of error codes that are not in use since Run-time version 3.1.


RT_ERR_INVALID_KEYSTORE_PASSWD 2510 Invalid value of certificate password

RT_ERR_INVALID_KEY_STORE_NAME 2521 Invalid Key Store Name (Reserved for Java)

RT_ERR_INVALID_CERTIFICATION_LOCATION 2528 Invalid CertificateLocation(Reserved for .NET)

Appendix D:Build Dependencies

This section provides a consolidated list of all the files required to build a Cloud or an On-premise application.

Notes

n In the table below, paths are given with respect to the installation directory of Sentinel Cloud Services,which by default is C:\Program Files\SafeNet Sentinel\Sentinel Cloud Services.

n To run an on-premise application, you will need to the install the Run-time from the \Redistributables\folder. For installation instructions, refer to Installation Guide.

InterfaceWindows

(Cloud or On-premise)

Linux


C (32-bit) Libraries(\RunTimes\C SDK\Win32\lib)

n scrdserializer.libn scrruntime.libn scrserializer.libn libhasp_windows.lib

External Libraries(\RunTimes\C SDK\Win32\externLib)

n genx.libn libcurl.libn libeay32MT.libn libexpatMT.libn liblogger.libn ssleay32MT.libn Wtsapi32.lib

Properties(\Configurations\)

n SentinelCloudRuntime.properties

Libraries(\RunTimes\C SDK\lib)

n libscrdserializer.an libscrruntime.an libscrserializer.an libhasp_linux.a

External Libraries(\RunTimes\C SDK\externLib)




C (64-bit) Include(\C SDK\include)

n cloudruntime.hn licenseclient.h

Libraries(\RunTimes\C SDK\lib)

n libscrdserializer_x64.an libscrruntime_x64.a

D

246 Appendix D: Build Dependencies

InterfaceWindows


Linux


Libraries(\RunTimes\C SDK\Win64\lib)

n Scrdserializer_x64.libn Scrruntime_x64.libn Scrserializer_x64.libn libhasp_windows_x64.lib

External Libraries(\RunTimes\C SDK\Win64\externLib)

n genx.libn libcurl.libn libeay32.libn libexpatMT.libn liblogger.libn ssleay32.libn Wtsapi32.lib



n libscrserializer_x64.an libhasp_linux_x86_x64.a

External Libraries(\RunTimes\C SDK\externLib)




Java Libraries(\RunTimes\Java SDK\Jars)

n ErrorCodes_en.propertiesn SaaSCommon.jarn SaaSxStream.jarn SentinelCloudRuntime-3.5.xxx.jarn SentinelCloudRuntime_P.dlln SentinelCloudRuntime_P_x64.dll



Third Party libraries(\RunTimes\Java SDK\Third Party libraries)

n bcprov-jdk16-145.jarn commons-collections.jarn commons-logging-1.1.jarn concurrent.jarn dom4j-1.6.1.jarn jcs-1.3.jarn junit-3.8.1.jarn log4j-1.2.15.jar

Libraries(\RunTimes\Java SDK\Jars)

n ErrorCodes_en.propertiesn SaaSCommon.jarn SaaSxStream.jarn SentinelCloudRuntime-3.5.xxx.jarn libSentinelCloudRuntime_P.son libSentinelCloudRuntime_P_

x64.so



Third Party libraries(\RunTimes\Java SDK\Third Partylibraries)

n bcprov-jdk16-145.jarn commons-collections.jarn commons-logging-1.1.jarn concurrent.jarn dom4j-1.6.1.jarn jcs-1.3.jar

InterfaceWindows


Linux


n quartz-all-1.7.3.jarn slf4j-api-1.5.8.jarn slf4j-log4j12-1.5.8.jarn xlightweb-2.13.2-jar-with-dependencies.jarn xpp3_min-1.1.4c.jarn cache.ccf

n junit-3.8.1.jarn log4j-1.2.15.jarn quartz-all-1.7.3.jarn servlet-api.jarn slf4j-api-1.5.8.jarn slf4j-log4j12-1.5.8.jarn xlightweb-2.13.2-jar-with-

dependencies.jarn xpp3_min-1.1.4c.jarn cache.ccf

.NET Libraries(\RunTimes\Dot NET SDK\Library)

n SentinelCloudRuntime.dlln SentinelCloudRuntime_P.dlln SentinelCloudRuntime_P_x64.dll



Third Party libraries((\RunTimes\Dot Net SDK\External libraries)

n BouncyCastle.Crypto.dlln Common.Logging.dlln log4net.dlln Microsoft.Practices.EnterpriseLibrary.Caching.dlln Microsoft.Practices.EnterpriseLibrary.Common.dlln Microsoft.Practices.ObjectBuilder.dlln Quartz.dlln Quartz.xml

Not Applicable

247

Appendix E:Caching (Cloud Deployment)

This section describes the caching feature of Sentinel Cloud Services.

E.1. OverviewThe Cloud applications store licenses in a cache (a temporary memory area), so that future requests for thelicenses can be served faster. The use of cache decreases the number of licensing calls sent to Sentinel CloudConnect, which enhances the performance of licensed application and the end user experience.

E.2. DescriptionWhen a user requests for a feature, Run-time serves the feature from cache if it exists, otherwise the request issent to Sentinel Cloud Connect. Sentinel Cloud Connect returns response for the requested feature, and inaddition returns all other features available in that product from a particular entitlement. Sentinel Cloud Run-time caches all features returned from Sentinel Cloud in memory.

Time to Live (TTL)

TTL stands for Time to Live that specifies how long to store a feature in cache before the feature expires.

Which License Models support Caching?

n Caching is done for non global-concurrent licensemodels, that is subscription and postpaid.

n Information is not cached for Global concurrent licensemodels, that is pre-paid and concurrent.

Behavior in the Case of Mixed License Models

If the product contains a mix of global concurrent and non-global concurrent licensemodels, the caching will bedone only in the case of non-global concurrent licensemodel requests. The features that are associated to non-global concurrent licensemodels will be returned for caching to Run-time.

For example, let us say that the Customer "cust1" has the belowmentioned entitlement for user “user1”.

n Entitlement: E1

n Product: P1

E

249 Appendix E: Caching (Cloud Deployment)

n Features and LicenseModels:

n Feature: F1 Pre-Paid (Global Concurrent)

n Feature: F2 Subscription-Concurrent (Global Concurrent)

n Feature: F3 Post-paid (Non-global concurrent)

n Feature: F4 Subscription (Non-global concurrent)

Case 1: If user1 of customer1 requests F1, then first it will be checked whether feature exists in cache for user1 inSentinel Cloud Run-time. It will not exist in cache in this case as feature is global concurrent, so request will go toCloud Connect, which will return response for feature F1 only with the information, not to cache it to SentinelCloud Run-time.

Case 2: If user1 of customer1 requests F3, first it will be checked in cache. The featuremight or might not existdepending upon whether user1 is requesting the feature for first time or not. If it is the first time, the request willgo to Sentinel Cloud Connect and it will return not only response for F3 but for F4 as well, along with the TTLvalue.

Case 3: If user1 of customer1 requests F4, then it will be served from cache assuming Case 2 has been executedbefore this request.

E.3. Cache Configuration in Run-timeRun-time uses different frameworks for caching on different platforms. Though there are various kinds ofconfigurations available, the Cloud Run-time is only tested with the in-memory caching. We recommendconfiguring only the belowmentioned settings for the Cloud Run-time:

Java

JCS cache is being used in Sentinel Cloud Run-time.

n File: cache.ccf

n Property: jcs.region.ClientFeatureCache.cacheattributes.MaxObjects

n Value: 1000 (Default)

.NET

Microsoft Enterprise Library is being used in Sentinel Cloud Run-time.

n File: Web.config

n Property: maximumElementsInCacheBeforeScavenging in cachingConfiguration section.

n Value: 1000 (Default)

C

No configuration settings required for caching in C.

Note:

The value should be set as per the RAM available on machine where Run-time integrated application runs. Sincecache depends upon memory and one record in cache roughly takes 120 bytes*, so we assume that at a given

point of time if 10000 users are only having 4 non-global concurrent features each, then total memory requiredis: 120 X 10000 X 4 = 4800000 (Roughly 4MB). Constantly application will take 4MB in RAM in this example. Cachevalue should be defined based upon factors mentioned. Also it is recommended to test with differentconfigurations and test data before deploying to the production environment.

E.4. Cache configuration in Cloud ConnectWhen Sentinel Cloud Connect generates response, it determines for each response whether to cache it or not,and how long to cache it. The value of the TTL property specifies the duration for which the response needs to becached. TTL can be specified against licensemodels and some negative scenarios as mentioned below:

License Model TTLs Default Value

Postpaid 1800 seconds

Subscription 1800 seconds

Negative Scenario TTLs:

License Model TTLs Default Value

Disabled Feature -255

Expired Feature -255

License does not exist -255

Note: To modify cache configuration in Cloud Connect, please contact SafeNet.

E.5. More about Caching BehaviorCache Expiration

When a cache entry expires, Run-time does not delete it from memory; in fact tries to refresh it from CloudConnect. If communication with Cloud Connect fails for any reason, Run-time keeps the entry into cache andcontinues to serve it to user. The entry is kept in to cache for the duration specified by theworstTimeoutMultiplier value (explained below). On next successful communication with Cloud Connect, theRun-time updates/removes the cache entry according to the response received from Cloud Connect.

The worstTimeoutMultiplier Property

If a cache entry expires and there is no communication with Cloud Connect, the entry will not be deleted fromcache until the following: worstTimeoutMultiplier X TTL. The worstTimeoutMultiplier property isspecified in the client configuration file.

For example, consider the case where:

n TTL value = 30mins

n worstTimeOutMultiplier value = 10

n An entry is added into cache at = 10:30 am

n There is no communication with Cloud Connect.

E.4. Cache configuration in Cloud Connect 250

251 Appendix E: Caching (Cloud Deployment)

In this case, the entry will not be removed from cache till 15:30 pm, as 30minutes X 10 = 5 hours

Cache Reaches Maximum Size

If cache is full and a request is received for addition in cache, then the LRU (Least Recent Used) entry is deleted toaccommodate the new request.

Appendix F:Handling of Abandoned Sessions

An abandoned session is one where the following API calls do not reach Sentinel Cloud Connect (for any reasonsuch as browser crash):

n logout

n refreshsession

In the case of concurrent licensemodel, if refreshSession or logout does not reach Cloud Connect for a specifiedinterval, the concurrent session is abandoned.

In the case of licensemodels except concurrent, if logout does not reach Cloud Connect for a specified interval,the session is treated as abandoned.

The refreshsession API is available only for Cloud licensing.

This topic explains how abandoned sessions are treated Cloud Run-time for Cloud and On-premise licensing.

Im po r t a n t

An ISV needs to contact SafeNet Support for setting the configuration properties related toabandoned sessions. The information given in this section can be useful in deciding thevalues of configuration properties.

F.1. Cloud Licensing

F.1.1. Configurations

A background process uses the following configurations to identify abandoned sessions and remove them:

Configuration Property Description

lastRefreshTimeStaleValue[Minutes]

This configuration is for all licensemodels, in which ISV application callsrefreshSession API frequently. In absence of API request, this propertyhelps decide whether to declare abandoned session or not. For example, iflastRefreshTimeStaleValue is 90minutes, then whenever backgroundprocess will run, it will check for records where stop time is null and lastrefresh time is less than (current time – 90)minutes. These sessions will betreated as abandoned sessions. Concurrency will be freed and sessions willbe completed by putting last refresh time into stop time.

F

253 Appendix F: Handling of Abandoned Sessions

Configuration Property Description

noLastRefreshStaleValue[Minutes]

This configuration is for all licensemodels. It is used in the cases where it isnot mandatory to call refreshSession API but it is required to identifyabandoned sessions to complete usage. Typically in these cases,completing an abandoned usage session is not that critical so these typesof sessions can be completed after a longer duration.

numberOfDaysToConsiderRecords[Days]

This configuration is required to search for a given time period, typicallyfrom (current time – x) days to improve performance. For example, if valueis 30 days for this property, then the background process will consider allrecords whosemodification time is greater than equal to (current time –30) days.

sessionTimeOutCountValue[Count]

This property is used to complete an abandoned session with defaultusage for count based models. For example if value is 10, then theabandoned session will be completed with 10 usage count for count basedlicensemodels.

sessionTimeOutTimeValue[Minutes]

This property is used to complete an abandoned session with default timefor time based licensemodels. This property is applicable for all licensemodels except subscription concurrent licensemodels. For the licensemodels where last refresh time is not derived, the abandoned sessions arecompleted by adding value of this property in start time.

F.1.2. Examples

This section covers various use cases for better understanding of how the background process completes theabandoned sessions.

Assumptions

Consider the following configuration values:

n Background Process Periodic Interval : 30minutes.

n lastRefreshTimeStaleValue: 1440minutes

n noLastRefreshStaleValue: 1440 (1 day)

n numberOfDaysToConsiderRecords: 30 days

n sessionTimeOutCountValue: 1

n sessionTimeOutTimeValue: 30minutes

The ISV application helps users in watching onlinemovies. The application fetches 15minutes buffer at a timeand before fetching next 15minutes buffer, it calls the refreshSession API and the next 15minutes buffer isfetched only if the session is valid.

This feature can be sold with various licensemodels, such as Subscription Concurrent, Pre-paid, andSubscription.

Case 1: Feature is sold as Subscription Concurrent

User started watching movie, ISV app calls login API for logged in user, it calls refreshSession API threetimes and after then user’s browser crashed.

Last Refresh Time for session record: 10:00 AM.

The background process runs at 10:15 AM.I It considers all records which were created/modified in last 30 daysand stop time is null and last refresh time < ( 10:15 – 90minutes). There won’t be any record.

Next, background process runs at 10:45, 11:15, still no record found. But when background process runs at 11:45it fetches one abandoned session as 11:45-90minutes = 10:15 and last refresh time less than 10:15withouthaving stop time present. Since this is concurrent feature so background process will free concurrency as well. Itwill put last refresh time in stop time for usage completion and if it’s a count based feature it will put valuespecified in sessionTimeOutCountValue usage count for this session.

User is watching a movie continuously for 3 days, ISV app calls login API for logged in user, it callsrefreshSession API after every 15 minutes regularly.

The background process will not terminate this session as whenever it runs it won’t find last refresh time as stale.In other words, last refresh timewill never be less than ( current time – 90minutes).

Case 2: Feature is sold as post-paid

A user started watching movie, the ISV application called the login API for logged in user, the refreshSes-sion API is called three times, and after that the user’s browser crashed.

Since it a non concurrent feature so there will be no impact of calling refreshSession API. Background processruns at 10:15 AM. It considers all records which were created/modified in last 30 days, and stop time and lastrefresh time is null, and start time < ( 10:15 – 24 hour).

Next, the background process runs at 10:45, 11:15, so on till next day 10:15 AM, but no record is found. But whenbackground process runs at 10:45, it fetches one abandoned session as 10:45-24 hours = 10:45 yesterday andstart time < 10:45 of yesterday. Also the last refresh and stop time is null. It will add the value ofsessionTimeOutTimeValue property in start time and put it into stop time to complete the usage record. If it is acount based feature, it will put the value specified in sessionTimeOutCountValue usage count for this session.

User is watching movies continuously for more than 3 days, ISV application calls login API for logged inuser, it calls refreshSession API after every 15 minutes regularly.

Since it a non concurrent feature so there will be no impact of calling refreshSession API. Since default value ofidentifying stale record is 24 hours for non-concurrent feature, so this session will be treated as an abandonedsession and will be forced complete by background process.

The ISV can increase the value of noLastRefreshStaleValue default time to the value that permitsmaximum duration of session.

F.1.3. Guidelines on Setting Configurations

The configurations given below are set by SafeNet Support in consultation with the ISV:

lastRefreshTimeStaleValue: 1440 minutes [Default].

This value has to be set depending upon the following considerations:

F.1. Cloud Licensing 254


1. How frequently ISV calls refreshSession API?

The ISV has to call refreshSession API periodically so that if refreshSession is successful, then only the ISVapplication allows the user to continue. The ISV needs to identify this periodic interval.

2. Howmany missed API calls or maximum time permitted between two refresh session calls?

Theremight be cases that ISV application calls refreshSession API but due to network error, it could notreach Sentinel Cloud Connect. ISV needs to decide if themissed refreshSession calls need to be consideredor not. The advantage is if even one or two calls do not reach Cloud Connect, the background process willnot clear these sessions. But, the disadvantage is if user’s session is killed due to crash or any otherreason, the background process will not clear it very quickly as it has to take care ofmissed refresh sessioncalls.

3. How aggressively ISV wants to detect abandoned sessions?

To detect abandoned sessions as soon as possible, an ISV needs to call refreshSession API at shorterinterval. The ISVmight not consider missed refreshSession calls due to network error or might considerjust onemissed refreshSession API call. Also he needs to run background process at aggressive periodicinterval.

4. What is network delay and record insertion cost for refresh session?

Though the refreshSession API is synchronous but there will be someminor delay due to networkcommunication and record processing cost, it has to be considered.

1 + 2 + 3 + 4 = Value of lastRefreshTimeStaleValue property.

Example: ISV decides to call refreshSession API every 30minutes. He permits onemissed refreshSessionAPI call and he expects network delay of 5minutes so the total is 65minutes. If background process runsevery 30minutes and user session crashed just after calling the login API, then in the worst case sessionwill be cleared in 65 + 30 = 95minutes.

noLastRefreshStaleValue: 1440 (1 day) [Default]

This property is for non-concurrency based licensemodels. This value has to be set depending upon thefollowing points:

1. How long session can continue, such as 1,2, or 10 days?

ISV needs to identify maximum duration of session permitted, whatever value he decides, the session willnot be forced complete by background process till that time.

2. What is the periodic job interval value ?

This value is important as it will be added in order to set final value of this property. Periodic job intervaltells how frequently usage will be sent to Sentinel Cloud Connect.

3. What is the network and record processing cost ?

Usage goes asynchronously, network delay and cost of insertion into Sentinel Cloud Connect has to betaken care of to set the final value.

1 + 2 + 3 = Value of noLastRefreshStaleValue property.

Example: If maximum session duration for non-concurrent licensemodel is 24 hour and periodic jobinterval is 60minutes and network/record processing cost is 10minutes than total comes out 1510

minutes (25 hours and 10minutes). If background process runs every 30minutes than in worst case whenuser’s session is crashed after login, session will be completed after 1510 + 30minutes = 25 hours and 40minutes.

numberOfDaysToConsiderRecords: 30 days[Default].

There can bemillions of records in usage history table, considering all records will be a performance bottleneck.This value has to be set depending upon the following things:

1. What is themaximum value of first two properties ?

The value of this property should be greater than first two properties.

2. What is background process periodic interval ?

Add the periodic interval of background process.

1 + 2 = Value of numberOfDaysToConsiderRecords property

We recommend adding fewmore days.

Example: If maximum value of first two properties is 1510minutes and periodic interval of backgroundprocess is 30minutes, than value of this property should be >= 2 days.

sessionTimeOutCountValue: 1 [Default]

ISV needs to decide what value to specify to complete usage record for count based models in case ofabandoned sessions.

sessionTimeOutTimeValue: 30 minutes[Default]

ISV needs to decide what value to specify in stop time after adding it to start time in order to complete usagerecord. This is for time based models in the case of abandoned sessions (non concurrent licensemodels only).

F.2. On-premise LicensingThe information given in this section is applicable for on-premise licensing.

F.2.1. Configuration Settings

Given below are the configurations that a background process uses to identify abandoned sessions andterminate them. The table lists configurations for both types of on-premise licensing, feature level andentitlement level:

Configuration Name Value Description

Feature Level Entitlement Level

stateSyncTime_min server_stateSyncTime_min 30 n License refresh timeand usage sync time forconnected mode of on-premise feature levellicensing.

F.2. On-premise Licensing 256




n Usage sync time fordetached mode(feature level andentitlement level) ofon-premise licensing.

tempContainerRefreshInterval_percent

NA 70 License of connected featurestore will be refreshed on thepercentage value of their timeslice.

cookieTimeOut NA 1440 Time after which the cookiewill not be valid.

numberOfDaysToConsiderRecords server_numberOfDaysToConsiderRecords

30 This configuration is requiredto search for a given timeperiod, typically from (currenttime – x) days, to improveperformance. For example, ifvalue is 30 days for thisproperty, then thebackground process willconsider all records whosemodification time is greaterthan or equal to (current time–30) days.

sessionTimeOutCountValue[Count]

server_sessionTimeOutCountValue[Count]

1 This property is used tocomplete an abandonedsession with default usage forcount based models. Forexample, if value is 10, thenthe abandoned session will becompleted with 10 usagecount for count based licensemodels.

sessionTimeOutTimeValue_min[Minutes]

server_sessionTimeOutTimeValue_min[Minutes]

30 This property is used tocomplete an abandonedsession with default time fortime based licensemodels.This property is applicable forall licensemodels. For thelicensemodels where stoptime is not derived, theabandoned sessions arecompleted by adding value ofthis property in start time.



startTimeStaleValue_min server_startTimeStaleValue_min 1440 This property helps decidewhether to declare a sessionas abandoned or not. Forexample, ifstartTimeStaleValue_min is 90minutes, then wheneverbackground process will run,it will check for records wherestop time is null and last starttime is less than (current time– 90)minutes. These sessionswill be treated as abandonedsessions. Sessions will becompleted by putting stoptime = start time +sessionTimeOutTimeValue_min.

In the table above, 'NA' refers to Not Applicable.

F.2.2. Examples

This section covers various use cases for better understanding of how the background process completes theabandoned sessions (for on-premise licensing).

This section provides generic examples that are applicable for both types of on-premise licensing, featurelevel and entitlement level. However, the configuration names used in this section are specific to featurelevel licensing, which you can substitute by corresponding names in entitlement level licensing whenrequired. Refer to the table above to find corresponding names.

Consider the following configuration values:

n Background Process Periodic Interval : 40minutes.

n startTimeStaleValue_min: 1440 (1 day)

n numberOfDaysToConsiderRecords: 30 days

n sessionTimeOutCountValue: 1

n sessionTimeOutTimeValue: 30minutes

Feature is sold as post-paid or Subscription Concurrent. A user started watching movie, the ISV application calledthe login API for logged in user, and after that the user’s browser crashed or user never called the logout API. Thebackground process runs at 10:15 AM. It considers all records which were created/modified in last 30 days, andstop time is null, and start time < ( 10:15 – 24 hour).

Next, the background process runs at 10:55, 11:35, so on till next day 10:05 AM, but no record is found. But whenbackground process runs at 10:45, it fetches one abandoned session as 10:45-24 hours = 10:45 yesterday and



start time < 10:45 yesterday. Also the stop time is null. It will add the value of sessionTimeOutTimeValue propertyin start time and put it into stop time to complete the usage record. If it is a count based feature, it will put thevalue specified in sessionTimeOutCountValue usage count for this session.

The ISV can increase the value of startTimeStaleValue_min default time to the value that permits maximumduration of session.

F.2.3. Guidelines on Setting Configurations

The configurations given below are set by SafeNet Support in consultation with the ISV:

startTimeStaleValue_min: 1440 (1 day) [Default]

This property is for all licensemodels. This value has to be set depending upon the following points:

1. How long session can continue, such as 1,2, or 10 days?

ISV needs to identify maximum duration of session permitted, whatever value he decides, the session willnot be forced complete by background process till that time.

2. What is the periodic job interval value?

This value is important as it will be added in order to set final value of this property. Periodic job intervaltells how frequently usage will be sent to Sentinel Cloud Connect.

3. What is the network and record processing cost?

Usage goes asynchronously, network delay and cost of insertion into Sentinel Cloud Connect has to betaken care of to set the final value.

1 + 2 + 3 = Value of startTimeStaleValue_min property.

Example: If maximum session duration for any licensemodel is 24 hours, periodic job interval is 60minutes,and network/record processing cost is 10minutes; then the total comes out to be 1510minutes(25 hours and 10minutes). If background process runs every 30minutes than in worst case when a user’ssession gets crashed after login, session will be completed after (1510 + 30)minutes = 25 hours and 40minutes.

numberOfDaysToConsiderRecords: 30 days[Default].

There can bemillions of records in usage history table and considering all records will be a performancebottleneck.

This value has to be set depending upon the following:

1. What is themaximum value of first property, that is startTimeStaleValue_min?

The value of this property should be greater than first properties.

2. What is background process periodic interval?

Add the periodic interval of background process.

1 + 2 = Value of numberOfDaysToConsiderRecords property

We recommend adding fewmore days.

Example: If maximum value of first properties is 1510minutes and periodic interval of background processis 30minutes, than value of this property should be >= 2 days.

F.3.4. sessionTimeOutCountValue: 1 [Default]

ISV needs to decide what value to specify to complete usage record for count based models in case ofabandoned sessions.

F.3.5. sessionTimeOutTimeValue: 30 minutes[Default]

ISV needs to decide what value to specify in stop time after adding it to start time in order to complete usagerecord.

If ISV wants to complete abandon session and restore concurrent session simultaneously , values oftempContainerLicenseTTL_min and license time slice in case of detached licenses should be considered.

Example: If tempContainerLicenseTTL_min is 60, detach interval is 1 hour , sessionTimeOutTimeValue is 60minutes. In this case, a concurrent session will be freed after 60minutes and abandoned session will have stoptime = login time + 60.


Appendix G:Capacity

About Capacity

Capacity, an integer value passed in a login session, is an indicator of load during the session. The load can havedifferent meanings in different environments. It could be number of subscribers consuming the application at agiven time or the number of cores on which an application is running. A capacity value is associated with a loginsession, and remains valid only for that session. A logout call for the session releases the capacity.

Capacity is not automatically determined by Run-time. Its value is provided by an application based onthe factors that it understands, such as number of cores or number of subscribers. Run-time only recordsthese values for the purpose of computing peaks for the specified interval.

Capacity values submitted by application instances are used to compute a cumulative value, called PeakCapacity, which determines the peak load achieved during a given period. Peak Capacity is defined as thecumulative load across a number of simultaneous sessions that are in use by a customer, in a given duration.

Suppose you are using capacity to represent the number of times a feature is consumed. You can laterdetermine peak loads on a feature for different time intervals during a given billing period. Based on peakcapacity values, you can bill your customers. The time intervals at which peak load is calculated is termed asgranularity.

The Capacity feature is available only for on-premise applications, for features with postpaid licensemodel.

Specifying Capacity

To implement the capacity-based usage tracking, capacity needs to be specified with the Run-time login call (asan optional parameter). It is then associated with a login session and used by Cloud Connect for computing thepeak capacity.

n A capacity value remains valid for a login session. With a logout call, the capacity gets free.

Computing Peak Capacity

To compute peak capacity, you need to call the Retrieve Peak Capacity web service of EMS, which uses thecapacity records to compute the peak capacity. This web service determines the peak capacity of one/allpostpaid feature(s) in a given duration across all entitlements of a customer. For details, please refer to EMS WebServices Guide.

G

263 Appendix G: Capacity

n The Retrieve Peak Capacity web service provides raw usage data, which you need to process fur-ther for billing purposes.

n The Retrieve Peak Capacity web service calculates peak capacity based on the data available inCloud Connect at a particular point of time.

n The Retrieve Peak Capacity web service provides information of only the postpaid features.

Defining Capacity Attribute

If you want to set a limit on the peak capacity so that you get notified when your customers approach or crossthe limit, you can use EMS to set Capacity Attribute. You can specify Capacity Attribute in the postpaid licensemodel associated to a feature by using EMS.

Capacity Attribute is used to enable processing of capacity values recorded by an application for postpaidfeatures. Based on Capacity Attribute, you can configure notifications and implement application logic (explainedin further sections).

Configuring Capacity-based E-mail Notifications

You can configure e-mail notifications in EMS that are sent when the peak capacity of a feature approaches orreaches the limit set in Capacity Attribute. The related notification rules available in EMS are: Capacity PeakExceeded and Capacity Peak Approaching. See EMS User’s Guide for details of notification rules.

Implementing Capacity-based Decision Making

You can use the getInfo Run-time API to query the capacity information and define application logic based on it.For example, you can configure your application to showwarning messages to user on exceeding peak capacitylimit.

The getInfo API returns Capacity Attribute and peak capacity of given feature(s) in the last N hours. For details,see section Retrieving Peak Capacity Information.

Example

This example explains how capacity information is processed and used.

Sample Data (Collected by Run-time)

To charge customers based on the capacity, a vendor needs to determine howmuch peak capacity is consumedin a billing period. Suppose, the customers used the application and recorded capacity for a particular feature,across a group of entitlements, in a day. The following table shows the sample capacity values recorded at thetime of login and logout.

Time Instance Capacity Requested (With login) Capacity Returned (At logout)

07:15 400

07:52 200

07:59 200

09:05 500

10:17 400

12:30 700

13:45 500

The Run-time sends the above data from application to Cloud Connect.

Computing Peak Capacity

For the above data set, a vendor can determine the peak value of the capacity for a given billing period. In thiscase, it is 1 day or 24 hours. The report data can be refined by specifying granularity as input. Granularityspecifies the time interval, in hours, at which peak capacity is reported. The entire duration is divided in timeslices equal to granularity.

Assuming a granularity of 1 hour, the peaks for each time slice are computed, as listed below:

Time Slice

(granularity is 1 hour)

PeakCapacity

Remarks

6:00 – 7:00 0 Indicates no capacity specified.

7:00 – 8:00 600 This equals 400 + 200.The logout at 07:59 is not considered. To calculatemaximumcapacity utilized during a time interval, the logout calls areignored.

8:00 – 9:00 400 No capacity recorded between 8-9. So the peak capacity duringthis interval is actual capacity until 09:00 , that is (400 + 200 – 200).

9:00 – 10:00 900

10:00 – 11:00 900

11:00 – 12:00 500

12:00 – 13:00 1200

13:00 – 14:00 1200

14:00 – 15:00 700

15:00 – 16:00till 23:00 - 24:00

700 For session created at 12:30, the subsequent logout has notarrived. It means that the amount of capacity blocked has notbeen released completely. The residual capacity is carried on tillthe logout happens, that is till capacity becomes zero. So, thepeak capacity remains same for all these intervals.

The graphical representation of this data by a vendor can be:

264

265 Appendix G: Capacity

The above data is for all features across all entitlements, but this can be refined down to a single entitlement orto a single feature, as required.

Defining Capacity Attribute and Configuring Notifications

If vendors want to set a limit on the peak capacity so that they could be notified when their customers approachor reach the limit, they could use EMS to set Capacity Attribute.

Say, for the above example, Capacity Attribute is 1500.

n EMS Notifications

Suppose the vendor configured the Capacity Peak Approaching notification rule, and set its percentagethreshold to 80%. If at any time, peak capacity becomes 1200 (80% of 1500 = 1200), a notification e-mail issent.

Similarly for the Capacity Peak Exceeded notification rule, if at any time peak capacity becomes 1500, anotification e-mail is sent.

n getInfo Notifications

The vendors can also query the above data by using the getInfo API. They need to specify capacityinterval in the optional parameter specifying the last N hours for which capacity information is required.Let us say, the capacity interval is 15 hours. The getInfo API will retrieve highest peak capacities for thelast 15 hours from the aggregated data available in Cloud Connect.

In the above example, getInfo will return the following: Peak Capacity =1200 and Capacity Attribute =1500.

266

Appendix H: GlossaryData Aggregation

Process of converting raw usage data into processed data that can be used for billing and metering.

Capacity

Indicator of load on a feature during a login session. The load can have different meanings in differentenvironments. It could be number of users consuming the application at a given time or the number of cores onwhich the application is running.

Capacity Attribute

A license attribute that is used to enable processing of capacity values recorded by an application for postpaidfeatures. You must set Capacity Attribute in EMS if you want to be notified when your customers approach orreach a specified limit.

Cache Interval

Maximum duration (in minutes) for which a licenses can be cached locally in the case of on-premise feature levelcaching mode.

Deployment Type

Specifies if the entitlement is created to license the applications deployed on-premise or on cloud.

Detached

A license that can be temporarily detached from the enterprise network for use on a remote recipient machinefor a defined period.

Detach Interval

Maximum number of hours for which a license can be detached for use in offlinemode.

Entitlement

The license granted by law or contract to use particular software (or a group of software packages) within its setlimits.

H

269 Appendix H: Glossary

Feature

The individual functional component of your application that can be independently controlled by a license—canbe an entire application, a module, or a specific functionality.

Feature Caching Mode

Specifies how licenses are pulled from Cloud Connect to an on-premisemachine—at feature level or atentitlement level.

Feature ID

A unique digit assigned to every feature. It is used by a product (or, an ISV application) to enforce authorizationat the feature level.

Feature Name

A unique name assigned to every feature. It can be used by an ISV application to enforce authorization at thefeature level (for on-premise deployments).

Globally Concurrent License

Licenses (like pre-paid and concurrent licenses) which need synchronization across the Cloud Run-time nodes.These licenses are served from Cloud Connect.

Isolated Machine

An on-premisemachine that is never connected to Internet.

Peak Capacity

The cumulative value of capacity. It indicates the cumulative load across a number of simultaneous sessions thatare in use by a customer.

Product

The entity which an ISV wants to sell to an end user. A product may havemultiple features in it.

On-premise

A deployment type where the protected application is deployed within the premises of an enterprisecustomer.There are two ways in which an on-premise application can be deployed:

n Server Deployment: The protected application is primarily hosted on an on-premise server machine,which is accessed by multiple thin clients.

n Client Deployment: Multiple instances of protected application run on end user machines.

For details, see Sentinel Cloud On-premise Deployment.

Station Count

Themaximum number of on-premisemachines on which an entitlement can be detached, in the case ofentitlement level licensing.

270

A

abandoned session 252acquireLicenseClient, API 29-31, 33, 168-170APIs

acquireLicenseClient

description 29

sample code 168-170

error codes 236, 238, 240getIdentity

description 35

sample code 171-173

getInfo

description 52

sample code 179-180, 183, 187

integrating APIs 207login

description 62

sample code 193-195, 197

logout

description 76

sample code 201-203

refreshSession

description 73

sample code 198-200

releaseLicenseClient

description 80

sample code 205-206

sample codes 167

transfer

description 42

sample code 175-178

authentication 19, 25

C

C structure 91, 95, 101, 105, 110, 112, 115, 118,121-122, 125, 129, 132, 136, 138, 141-143,145, 147, 150-154, 158

cache 248Cache Interval 19caching 248capacity 55, 262

attribute (limit) 108, 122-123, 263define 262notifications 263, 265peak 262

capacity attribute 108certificates, security 25classes

AcquireClientOptionalParam class 153AcquireClientResponse class 154attribute class 128-129concurrency class 119-120Configuration class 155-156entitlement class 104feature class 113-114format class 93-94GetIdentityOptionalParam Class 145GetIdentityResponse Class 146GetInfoOptionalParam Class 122GetInfoResponse class 124-125license class 117LicenseAttribute class 109licenseClient class 86licenseException class 160-161LoginOptionalParam class 131

Index

273 Index

LoginResponse class 134-135, 140LogoutOptionalParam class 138product class 111SaaSFeatureNode class 88-89scope class 97, 99TransferOptionalParam class 148-149TransferResponse class 151

client configuration file 217cloud connect

overview 1cloud run-time

APIs 27classes 85enumerations 163overview 1

compatibility 26concurrency 118, 252concurrent limit 106contact us xiiCount Based 107current license state 148-150

D

detach 8, 20, 27, 42, 65, 87, 152, 165, 268detach interval 148-150Detach Interval 268documentation resources xii

E

EMSoverview 1

end date 106enumerations 164-165eventually consistent 127

F

Feature Caching Mode 7

G

getIdentity, API 35, 37, 39-40, 171-173getInfo, API 52, 57, 59-60grace 106grace limit 106

H

HMAC-SHA1 26HTTPS 25hybrid 7

I

instance counting 106

L

last aggregation time, capacity 55license attribute 105login, API 62, 67-68, 70logout, API 76-79LRU 251

M

machine registration 11, 19maximum usage limit 106measurement unit 106Message Signing 25

O

on-premise 7acquirelicenseClient 29configuration

Deployment Type 220

UsagePath 221

UserInfoCache 221

entitlement level 7-8feature level 7, 17getIdentity 35getInfo 53login (entitlement level) 65login (feature level) 65logout 76releaseLicenseClient 80transfer 42

on-premise run-time 7

P

peak capacity 55, 122-123, 262notifications 265

Index 274

retrievePeakCapacity 262PKCS12 26platform support 26proxy 221Public CA 26

R

refreshSession, API 72, 74-75, 198-200releaseLicenseClient, API 80-82

S

sample codes 167secret 213Sentinel Cloud

client configuration file 217client web services 6components 3connect 4data engine 6directory services 6EMS 5overview 2run-time 4

session 106SFNT_SCR_CONFIG_FILEPATH 226signature 26SSL 25start date 105station count 8

T

technical support xiiTime Based 107transfer, API 42-43, 46, 49, 175-178TTL 248

U

usage count 106usage type 107usageCountMultiplier 127

W

worstTimeoutMultiplier 250

Documents

Sentinel Cloud Services - Run-time Guidedocumentation.sentinelcloud.com/3.5/PDF/Sentinel Cloud...TableofContents Preface xii Chapter1:Overview 1 1.1.WhyUseSentinelCloudServices? 2