Table of Contents

• Overview
• Products and product types
• Licenses
  • License types
  • Commercial models and terms
  • License properties
• Identity
  • User identity
  • Instance identity
• Sessions
• Features
• Components
• Offline use
• Grace periods

Overview

elm is a cloud licensing service. A vendor defines products in the elm portal and issues licenses for them to customers. The vendor's software uses an elm client SDK (.NET, Java, Python, JavaScript, C++ or Ruby) to register with a license key and then validate sessions against elm. For the SDK quick starts, see the documentation home page.

Products and product types

A product is identified by a GUID and has its own public key, which the SDKs use to secure communication with elm. Each product has one of four types:

Product type	What is licensed	SDK entry point
Desktop app	A user on an instance (machine)	ControlManager
Server	A server instance; server products cannot have components	ServerControlManager
Web app	A server instance, plus each user registered against it and their sessions	ServerControlManager + UserControlManager
Web API	Consumable token components, checked out per call with a license-scoped API token	Web API (no control manager)

Products also have versions. Component token requirements are defined per version, so the version string your application reports matters once you use components.

Licenses

A license belongs to a customer (a company or a business unit of one), covers one product, and is identified by its license key. It carries entitlements (user, instance and session counts), optional restrictions, features, component entitlements and terms. A license can be deactivated, and newly created licenses can require approval.

License types

The license type decides which entitlement count is enforced:

• Named user: limits the number of registered users.
• Concurrent: limits the number of active sessions (optionally counting unique users rather than sessions). Active offline checkouts count against the limit.
• Node-locked: limits the number of registered instances.
• Unrestricted: no seat limit; typically combined with component entitlements.

Restrictions can be layered on any type: users per instance, instances per user, sessions per user, sessions per instance, sessions per user per instance, email activation, and a minimum assignment length before a seat can be reassigned.

Commercial models and terms

A license's commercial model describes how it is sold: Perpetual with M&S, SaaS, Lease, Free trial or Freeware. Terms are time-bounded periods (start and end date); a license is active while it has a current term, and renewing a license means adding a term. When a license expires, sessions report LicenseExpired.

License properties Preview

Vendors will be able to attach key-value properties to a license (keys of letters, digits, _, - and .; values up to 10,000 characters). Client API v3.5 returns them as custom_data on successful session and validation responses only, so they can carry per-customer configuration, including secrets.

Identity

User identity

A user identity is a set of key-value strings that identifies the person using the software. It must come from a source the user cannot spoof: the operating system or directory account (the .NET, Java and C++ SDKs provide ActiveDirectoryBasedUserIdentity, which records UserName and, on a domain, UPN), or for web apps the account ID from your own authentication system. Never use values the user types in, such as an email address. The name and email collected at registration (UserInfo) are contact details, not identity.

Instance identity

An instance identity identifies the machine or server. It is a set of key-value pairs, each with a weight, a case-sensitivity flag and (for array values such as MAC addresses) an allowed number of differing entries. The identity's maximum mismatch count (default 1) lets hardware change a little without invalidating the instance. The hardware helpers in the .NET, Java, C++ and JavaScript SDKs add the host name, CPU identifier, a volume hash, and the IP and MAC addresses; the Python SDK has no hardware helper, so you supply the values. A change beyond the tolerance is reported as InconsistentRegistration.

Sessions

After registration, the application begins a session, extends it periodically while it runs, and ends it when it closes. Each validation returns whether the session is valid, an InvalidReason when it is not (for example NoSeatsAvailable, SessionRevoked, InstanceDisabled), and the license's features. Ending sessions promptly frees concurrent seats for other users. Session history feeds elm's usage reporting.

Features

Features are named on/off flags defined on the product and enabled per license (and optionally per instance or user). They can be organized into feature groups and are typically used for editions. They carry no separate terms or counts; the session's validated state lists the features that are on.

Components

Components are independently licensed parts of a product, optionally grouped into component groups. A license grants them through component entitlements, each with its own terms. There are three types:

• Session: limits how many sessions can have the component checked out at once.
• Checked-out token: a pool of tokens; checking out the component takes the number of tokens its version requires, and checking in returns them.
• Consumable token: tokens are spent when used and not returned.

An entitlement can renew every day, week, month or year, can allow overage (a fixed count or a percentage above the entitlement), or can be unlimited. Components are not available for Server products, and Web API products use consumable tokens only.

Offline use

• Offline license checkout: on a concurrent license (or a server product), a seat can be checked out for a requested duration; it counts as an active seat until it expires or is checked back in.
• Offline component token checkout: tokens from a component entitlement can be checked out for offline use the same way.
• Full license checkout: an unregistered desktop or web app license can be checked out as a whole to an elm Lite server for air-gapped sites.

Grace periods

• Validation failure grace period: if elm cannot be reached, a client that validated successfully before keeps working for the license's grace period (set per license, 7 days by default). After that, validation fails with ServiceUnreachable.
• Unregistered grace period: a client-side setting (GracePeriodForUnregisteredProduct on the control strategy) that lets a product run before it is registered.