Contents

• Overview
• Calling API endpoints
• Convenience features
• Using Slascone Client in your application
• Release notes

For more information about SLASCONE:

https://slascone.com/ and/or https://support.slascone.com/

Slascone.Client

Overview

A NuGet package to access the SLASCONE (OAS 3.0) API.

This package provides a comprehensive .NET Standard 2.0 client for interacting with the SLASCONE software licensing and analytics solution. It streamlines integration with the SLASCONE API by providing methods for managing licenses, devices, and environments.

While direct access of the API via HttpClient is possible, this library significantly reduces complexity through high-level helper functions. These functions go beyond basic API calls, providing high-level utilities that help developers handle digital signature verification, environment detection and device fingerprinting with minimal effort. By leveraging these features, you can ensure secure license validation, adapt to different deployment scenarios (such as cloud or virtual machines), and reliably generate or retrieve unique client identifiers.

Particularly beneficial for use cases that require offline support or operate without network connectivity.

Example applications using the Slascone.Client library on GitHub

You can find example applications using the Slascone.Client library on our Slascone GitHub repository. These samples show how to integrate the client into .NET projects, including WPF and C# console apps, and demonstrate key features such as license activation, heartbeat handling, and offline license support.

• https://github.com/SLASCONE/SLASCONE-demo-wpf-nuget
• https://github.com/SLASCONE/SLASCONE-demo-csharp-nuget

Calling API endpoints

Corresponding to the controllers of the SLASCONE RestAPI, the Slascone.Client library provides a set of interfaces that represent the various API controllers. The Swagger UI, which provides an overview of the controllers and all endpoints, is available at the URL https://api365.slascone.com/swagger.

The main entry point is the ISlasconeClientV2 interface, which exposes a set of strongly-typed API controller clients for all major SLASCONE features, including license management, provisioning, customer and product management, and more.

Administration

The Administration interface provides methods to manage Custom Lists. Um weitere eher ungewöhnliche Verwaltungsaufgaben durchzuführen, rufen Sie die Endpunkte der Administration-Controller direkt z.B. über einen HttpClient auf.

Customer

The Customer interface provides methods to manage customers, including creating, updating, and retrieving customer information and customer users.

DataExchange

The data exchange interface provides methods to manage data exchange operations, such as importing and exporting data related to licenses, customers, and products. You can use this interface to synchronize data between your external systems and the SLASCONE backend, e.g. Customer Relationship Management (CRM) systems or Enterprise Resource Planning (ERP) systems.

DataGathering

The data gathering interface provides methods to manage data gathering operations, such as collecting usage analytics data from your applications.

Product

The Product interface provides methods to manage products, including creating, updating, and retrieving product and product related information, such as features, limitations, and variables as well as software releases.

Template

The Template interface provides methods to manage templates (product editions).

License

The License interface provides methods to manage licenses, including creating, updating, and retrieving license information. It also includes methods for license validation and heartbeat management.

LicenseBundle

The LicenseBundle interface provides methods to manage license bundles, which are collections of licenses of different products that can be assigned to customers or users.

Lookup

The Lookup interface provides methods to manage lookup data, such as license types, product types, and other predefined values used in the SLASCONE platform.

Provisioning

The provisioning interface assembles the main functionality needed in client applications, such as license activation and validation.

Convenience features

Some of the most utilized convenience functions include:

• Digital Signature Verification: Methods like IsFileSignatureValid allow you to verify the authenticity and integrity of license or activation files using asymmetric or symmetric cryptography.
• Offline License Handling: Functions such as GetOfflineLicense enable applications to read and validate license information even when temporarily disconnected from the SLASCONE backend.
• Environment Detection: Utilities in LinuxDeviceInfos and WindowsDeviceInfos help detect if the application is running in a Docker container, virtual machine, or cloud environment by checking for specific files or system properties.
• Unique Client ID Retrieval: The client provides access to various hardware and system identifiers (e.g., machine ID, MAC addresses, DMI product UUID) to generate or retrieve a unique device fingerprint, which is essential for license assignment and tracking.
• System Information Logging: Methods like LogDeviceInfos collect and format detailed device information for diagnostics, support, or analytics purposes.
• HTTP Header Management: The client exposes methods to set, add, or retrieve custom HTTP headers, supporting advanced integration scenarios and user tracking.

These convenience functions are accessible through the ISlasconeClientV2 interface and its platform-specific helpers, making it easy to integrate robust licensing and device management features into your application.

Handling of temporary offline scenarios

License information that is retrieved from the SLASCONE backend is stored in a temporary offline license file. In case the application is not able to connect to the SLASCONE backend, e.g. due to network issues, the application can use the temporary offline license file to validate the license. The temporary offline license file is stored in the application data folder specified by SetAppDataFolder.

Custom logic for storing and retrieving license information for offline use

The ITemporaryOfflineLicenseHandler interface defines methods for writing and reading license information and its associated signature, as well as managing session data. Instead of using the default implementation of the temporary offline license handler that stores data in the application data folder, you can implement the ITemporaryOfflineLicenseHandler interface to provide custom logic for storing and retrieving license information for offline use. Use a custom implementation if you don't want to store the data in the local file system but e.g. in a database.

Set the custom implementation of the ITemporaryOfflineLicenseHandler interface using the SetOfflineDataStorageStrategy method of the ISlasconeClientV2 interface. Do not use the methods SetAppDataFolder, SetTempOfflineLicenseFilenames, and SetTempOfflineSessionFilename when using a custom implementation of the ITemporaryOfflineLicenseHandler interface, as these methods are only applicable for the default implementation that stores data in the application data folder.

/// <summary> /// Defines a strategy for temporarily storing offline data. /// </summary> public interface ITemporaryOfflineDataStorageStrategy { /// <summary> /// Writes license information and its associated signature. /// </summary> /// <param name="licenseInfo">A byte array containing the license information to write.</param> /// <param name="signature">A string representing the signature for the license information.</param> void WriteLicenseInfo(byte[] licenseInfo, string signature); /// <summary> /// Retrieves the license information and its associated signature. /// </summary> /// <returns>A tuple containing the license information as a byte array and the signature as a string.</returns> (byte[] LicenseInfo, string Signature) ReadLicenseInfo(); /// <summary> /// Writes session data to the storage. /// </summary> /// <param name="sessionData"></param> void WriteSessionData(string sessionData); /// <summary> /// Retrieves the session data from the storage. /// </summary> /// <returns></returns> string ReadSessionData(); /// <summary> /// Removes the session data from the storage, effectively clearing any stored session information. /// </summary> void RemoveSessionData(); /// <summary> /// Appends lines of text to a file associated with the specified type name. /// </summary> /// <param name="typeName">The name of the type associated with the file.</param> /// <param name="lines">The lines of text to append.</param> void AppendLines(string typeName, IEnumerable<string> lines); /// <summary> /// Returns an enumerable collection of lines associated with the specified type name. /// </summary> /// <param name="typeName">The name of the type for which to retrieve lines.</param> /// <returns>An enumerable collection of strings representing the lines.</returns> IEnumerable<string> ReadLines(string typeName); /// <summary> /// Clears the lines associated with the specified type name, effectively removing any stored data for that type. /// </summary> /// <param name="typeName">The name of the type for which to clear lines.</param> void ClearLines(string typeName); }

Signature verification of offline license files

If the license validation is supposed to be done offline, the Slascone.Client library provides methods to verify the digital signature of the license file to ensure its integrity and authenticity.

Using Slascone Client in your application

Instantiation of a Slascone.Client instance

To create an instance of the client, use the SlasconeClientV2Factory class, which provides static methods to build and configure an ISlasconeClientV2 implementation. The client supports advanced configuration options such as custom HTTP headers, certificate validation, offline license handling, and more.

string ApiBaseUrl = "https://api.slascone.com"; Guid IsvId = Guid.Parse("2af5fe02-6207-4214-946e-b00ac5309f53"); string ProvisioningKey = "your-provisioning-key"; _slasconeClientV2 = SlasconeClientV2Factory.BuildClient(ApiBaseUrl, IsvId, ProvisioningKey);

Key components:

• ISlasconeClientV2: The main interface aggregating all API controller clients and configuration methods.
• SlasconeClientV2Factory: Factory class for creating and initializing ISlasconeClientV2 instances.

Example for creating a license heartbeat:

var heartbeatDto = new AddHeartbeatDto { Product_id = Guid.Parse("your-product-id"), Client_id = clientId, Token_key = GetTokenKeyFromTemporaryOfflineLicense(), User_id = _authenticationService.IsSignedIn ? _authenticationService.Email : null, Software_version = SoftwareVersion, Operating_system = OperatingSystem }; var result = await _slasconeClientV2.Provisioning.AddHeartbeatAsync(heartbeatDto);

Configuring Slascone.Client

To configure the Slascone.Client, you need to provide the base URL of the SLASCONE API, your ISV ID, and your provisioning key. These parameters are essential for authenticating requests and ensuring that your application can communicate with the SLASCONE backend.

SetSignatureValidationMode(int signatureValidationMode)

Sets the validation mode for the signature header (none, symmetric, or asymmetric).

SetAppDataFolder(string appDataFolder)

Sets the application data folder for storing license information for offline use. If no application data folder is specified, features like temporary offline license handling will not be available.

SetSignatureCertificate(byte[] rawData)

Sets the certificate (public key) used to verify signatures (asymmetric mode).

SetSignaturePublicKeyXml(string publicKeyXml)

Sets the RSA public key from an XML string for signature verification. The public key can be retrieved in XML format or as PEM file from the SLASCONE licensing portal.

SetSignaturePublicKey(PublicKey publicKey)

Sets the RSA public key directly. The public key can be retrieved in XML format or as PEM file from the SLASCONE licensing portal.

SetProvisioningKey(string provisioningKey)

Sets the provisioning key for authentication. The provisioning API key can be retrieved from the SLASCONE licensing portal.

SetAdminKey(string adminKey)

Sets the admin key for authentication. The admin API key can be retrieved from the SLASCONE licensing portal.

SetBearer(string bearer)

Sets the bearer token for authentication. The bearer token is a JWT token that is provided by an identity provider e.g., Azure AD B2C.

SetLastModifiedByHeader(string lastModifiedById)

Sets the 'LastModifiedBy' HTTP header for requests. The LastModifiedBy content will be noted in the history entries of the SLASCONE backend, allowing you to track who made changes to the data.

SetHttpClientTimeout(TimeSpan timeout)

Sets the HTTP client timeout for API requests. The defaut timeout is 100 seconds. This timeout applies to all HTTP requests made by the client.

SetCheckHttpsCertificate(bool check = true)

Enables or disables HTTPS certificate chain of trust checking.

SetHttpRequestHeader(string headerName, string headerValue)

Sets (adds or replaces) a specific HTTP header for requests.

AddHttpRequestHeader(string headerName, string headerValue)

Adds a specific HTTP header for requests (can add multiple values for the same header).

TryGetHttpRequestHeader(string headerName, out IEnumerable values)

Tries to get the value(s) of a specific HTTP header.

SetTempOfflineLicenseFilenames(string licenseFileName, string signatureFileName)

Sets the filenames for temporary offline license and signature files. By default the filenames are license.json and license_signature.txt. These files are used to store license information for offline use, allowing the application to validate licenses even when not connected to the SLASCONE backend. The files are stored in the application data folder specified by SetAppDataFolder.

SetTempOfflineSessionFilename(string sessionFileName)

Sets the filename for the temporary offline session file. By default, the filename is session.token. The session file is stored in the application data folder specified by SetAppDataFolder.

Release notes

2.1.1041:

• Defines the ITemporaryOfflineLicenseHandler interface for handling temporary offline license files, allowing applications to implement custom logic for storing and retrieving license information for offline use.

2.1.1011

• Replay Attack Protection: Enhanced security by implementing nonce-based request verification. When asymmetric signature validation is enabled (SetSignatureValidationMode(2)), the client automatically adds a unique X-Nonce header to each request. The server signs this nonce and returns it in the X-Nonce-Signature response header, which the client verifies to ensure the response is authentic and not a replayed message from a previous session.

2.1.961

• New versions of the ISlasconeLicenseClientV2.GetConsumptionHeartbeatsAsync() with new parameters transaction_id, user_id, and client_id
• New attribute client_name in LicenseInfoDto

2.1.943

• New versions of GetAllCustomersAsync(), GetCustomerTypesAsync(), GetLicenseTypesAsync(), GetAllProductsAsync(), GetAllTemplatesAsync() methods with 'name' parameter
• New DeviceLicenseAssignmentDto property: Suspended_until_utc
• New LicenseFilterDto property: Is_suspended_token
• New SessionDto property: Duration
• New TemplateVariableDto property: Is_required
• New CloseAllSessions() endpoint in Provisioning controller
• Updated dependencies

2.1.917

• Fixed User-Agent header version number

2.1.874:

• Added 'start_date' to license information for online and offline licenses

2.1.847:

• Added value array to analytical heartbeat
• Software shipment: new flag 'is_latest'

2.1.842:

• Offline usage analytics
• Renovate Readme.md; added release notes section and documentation for the Slascone.Client configuration and convenience methods.

2.1.838:
Introduces product controller and start date

• Added product controller
• Added start date