ionic-js-sdk 2.3.0

Ionic JavaScript (JS) software development kit (SDK).

The Machina JavaScript SDK allows developers to incorporate core features of the Machina platform in their applications.

  • As a developer, you should have a free Machina tenant and gone through the JavaScript "Hello, World!" example. If you have a tenant and not gone through the "Hello, World!" example, then go here. If you don't have a tenant, then proceed to Start for Free on Machina Developers. Be sure to select 'chrome' and 'javascript' logo from the menu panel available at the top of the page. Alternatively, you can explore other SDKs available for use with the Machina platform.

  • If you are an Ionic customer with access to and control over the Ionic on-prem services for your tenant, please ensure that your Enrollment Server configuration is set up for use by the JS SDK.

JS SDK Requirements

  • Browser support for WebCrypto API and SubtleCrypto
    • Chrome 37+
    • Firefox 34+
  • SubtleCrypto interface
    • Access to the SubtleCrypto API is restricted to secure origins (which is to say https:// pages)
  • Ionic Enrollment Server configuration with a setting for JS SDK enablement.

Getting The SDK

The latest version of JS SDK can be found at https://api.ionic.com/jssdk/latest/.

Complete JS SDK version listing - links to all the publicly released versions.

  • If your tenant is in the Preview environment, use Preview listings page.
  • If your tenant is in the DevX environment, use DevX listings page.

JS SDK Architecture

Flow diagrams and security considerations are presented here.

Machina platform features supported by JS SDK

The following Machina platform functions are supported:

  • Enrollment: create and store secure enrollment profiles (SEPs) for trusted devices. See related documentation for details.
  • Key requests: create, fetch (aka 'get'), and update Machina data protection keys. See 'Key Management' section on the related documentation page. On the same page, refer to the 'Key Tasks' heading in the navigation column for additional request-specific documentation.
  • Protected attributes: attributes associated with Machina keys can be protected so they are not readable by the Machina platform.
  • Encryption: encrypt and decrypt data with Machina protection keys using cryptographic primitives available in a browser window context.
  • Chunk Data Format: encode encrypted data along with the associated key tag (aka keyId).
  • Key Attributes: add mutable (updateable) and immutable (cannot be changed once set on the key) attributes.
  • Request Metadata: specify metadata such as device or application information.

Getting Started - Hello World application

This sample application demonstrates user (device) enrollment and string encryption/decryption using the latest version of JS SDK.

  • index.html

    • Loads the latest version of the Machina JS SDK library sdk.bundle.js
  • index.js

    • Uses the ISAgent interface to store and retrieve user (device) profile information and to encrypt/decrypt text:
      • enrollUser() - creates a new Machina user (device) profile, stores it encrypted in localStorage.
      • loadUser() - loads an existing enrollment profile from localStorage.
      • encryptStringChunkCipher() - creates a new Machina data protection key and uses it to encrypt the user-specified text.
      • decryptStringChunkCipher() - requests the Machina data protection key associated with the encrypted string from the Machina platform, uses it to decrypt the text.

The easiest way to run the sample is with http-server. This NodeJS tool will turn your current directory into a static server.

In a node-aware console run:

npm install -g http-server

In a text editor or IDE:

  • Open index.js
  • Edit the enrollmentUrl property and set it to the applicable enrollment URL for your Machina tenant
  • Save the file

Back in the console run:

http-server .

Then open your Chrome browser and navigate to localhost:8080

Enter credentials of your choice - these values correspond to 'userId' and 'userAuth' parameters provided to JSSDK function enrollUser(). NOTE: these credentials are different from the authentication credentials used during enrollment. See Profile Info for more information.

Upon successful completion of the enrollment process, these parameters are used to store the encrypted enrollment profile in LocalStorage.

Additional Developer documentation

Additional developer resources are available at dev.ionic.com and on GitHub:

Release Notes

2.3.0 - Latest

  • Added New API functions:

  • Addressed miscellaneous documentation action items: typos, wording, links, browser support.

  • Removed 'utf8' and 'ascii' output encoding for createKeys() and getKeys() output.

  • Added getKeys() support for "legacy" keys (keys created without attribute signing)

2.2.1

  • Added description HTML meta tags to documentation pages
  • Updated the documentation to mention Firefox support
  • Minor documentation fixes

2.2.0

  • External ID support
    • getKeys() now supports querying for Machina protection keys by external ID
  • SDK version string
    • All requests processed by JSSDK now include a version string.
    • Machina Dashboard users can access this value via the 'ionic-agent' property (eg on the Machina Dashboard Key Fetch Request page).
  • Agent initialization improvements
    • The ISAgent constructor now supports configuration parameters
      • When specified, 'metadata' is associated with all requests handled by this ISAgent instance
      • When specified, user and application information ('appId', 'userId', 'userAuth') is used to load a default profile (or a specific one if 'deviceId' is also specified).
  • Active Profile
  • Agent Metadata
  • Updated documentation
    • Updated the 'hello world' sample with usability improvements
    • Added code samples, expanded some of the previously-hidden/partial content (eg constants module contents)
  • Miscellaneous bugfixes and error-handling improvements

2.1.0

  • Additional key response data
    • createKeys()/getKeys()/updateKeys() - the response object now specifies 'obligations' for Machina keys, as specified by the key server.
    • createKeys() - the response object now returns 'keyRef', 'attributes', and 'mutableAttributes' values as specified in the key create request.
    • getKeys() - the function now returns 'msig' and 'csig' values as specified by the key server.
    • updateKeys() - To be consistent with the other functions, the 'id' attribute is now specified as 'keyId'. Additionally, the function now returns 'mutableAttributes' as specified in the key update request.
  • Bugfixes
    • Protected attributes support - attributes associated with Machina keys can be protected so they are not readable by the Machina platform. This version adds support for these attributes, fixing issues present in the previous version 2.0.0.
    • Key encoding - keys returned by createKeys() or getKeys() functions can be returned in different encoding formats. In version 2.0.0, only the 'hex' encoding worked. This version supports 'hex', 'base64', 'ascii', and 'utf8' encodings.
    • This version validates the attributes (mutable and fixed) object against the IDC v2.4 specification-allowed format. If the type or contents of the object are invalid, JS SDK now returns a descriptive error to that effect.
    • The management of active session state was using the wrong data structure for maintaining active profiles state. The bug was fixed and the related profile management code was refactored for improved maintainability and optimization.
    • The error messages for KEY_VALIDATION_FAILURE (50007) and CRYPTO_ERROR (50001) were previously missing. This version properly returns error messages for these error conditions.
    • This version fixes an issue with returning non-SDK errors (eg. IDC/server errors, runtime errors, etc). In previous versions, some of the underlying error details were incomplete or hidden.
  • Expanded documentation
    • The tutorials section now contains an Architecture Overview.
    • The Hello World section was moved back from tutorials to this (main README) page for easier access.
    • The license header had a typo in the @author tag - the ',' was removed from the company name.
    • The version page hosting the internal JS SDK component now contains a relative path link to the applicable API (JSDoc-generated) documentation.

2.0.0

  • The first general availability (GA) release of the JS SDK.