Machina User Documentation

Machina Platform

Release Notes v 5.3

Contact Us:

If you have comments about this documentation, submit your feedback to:

Documentation@ionicsecurity.com

Copyright notice:

Copyright © 2020 Ionic Security Inc. All rights reserved.

Ionic Security, the Ionic Security logo, and Machina Platform are trademarks or registered trademarks of Ionic Security or its affiliates in the U.S. and other countries. Other names may be trademarks of their respective owners.

The product described in this document is distributed under licenses restricting its use, copying, distribution, and decompilation/reverse engineering. No part of this document may be reproduced in any form by any means without prior written authorization of Ionic Security and its licensors, if any.

The documentation is provided “as is” and all express or implied conditions, representations and warranties, including any implied warranty of merchantability, fitness for a particular purpose or non-infringement, are disclaimed, except to the extent that such disclaimers are held to be legally invalid. Ionic Security shall not be liable for incidental or consequential damages in connection with the furnishings, performance, or use of this documentation. The information contained in this documentation is subject to change without notice.

Microsoft Office, Microsoft Windows, and Internet Explorer are registered trademarks of Microsoft Corporation. All screenshots of these programs are used with permission from Microsoft.

General Enhancements

Billing Notification Banner

A Notification Banner has been added to the Machina Console which indicates when a customer account is approaching or has exceeded the allotted transaction limits. This banner is displayed at the top of the console upon login. Information about the tiers, and their current transaction limits can be found at https://ionic.com/pricing/

 

New Policy Datatypes

The inclusion of new Policy Data Types in the Machina Policy Builder (Advanced Section). These data types are currently supported but must be edited using JSON. Moving forward the following policy types will be offered:

• String
• Integer
• Double
• IpAddress
• DateTime
• Date
• Time

KeyValue Store UI/API

The 5.3 Machina Console release introduces the Key Value Store API endpoints to improve ease of use around customer integrations. This is a generic customer facing integration API which allows Machina users to upload/control/access their integration(s) configurations on their hosted Machina systems. This feature also allows Machina users to build their own key/value pairings within Machina to allow quick and easy configurations.

• API - Machina 5.3 introduces new end-points to improve our External Key Management functionality and ease of use with partners like Google. Machina now allows users to configure their Google EKM system via our API vs our previous method which required Customer Success engagement.

To Configure your key-value pair via the API

1. Log into Machina
2. Navigate to Users -> Select Users -> Select API Keys
3. Create API Key (API Key only requires API Access and KVStore Manage/Read)
4. Store your API Securely
5. Posting Data to the KVStore

   a. INPUT:

   curl --request POST 'https://<hostname>/api/<tenant_id>/kvstore/Example' --

   header 'Authorization: Bearer <Token_ID>' --header 'Content-Type:text/plain' --

   data-raw 'Sample'

   OUTPUT:

   {

   "_createdBy": "5fda253349a49e336dfd9226",

   "_createdTs": 1618508904,

   "_updatedBy": "5fda253349a49e336dfd9226",

   "_updatedTs": 1618508904,

   "_version": 1,

   "changedBy": {

   "apiKey": {

   "exists": "exists",

   "id": "6058bfa3fc8e031c30fdc913",

   "name": "API_KEY_NAME"

   },

   "id": "5fda253349a49e336dfd9226",

   "tenantId": "<tenant_ID>"

   },

   "id": "60787c68e106b5789efd921a",

   "key": "Example",

   "tenantId": "5fda253249a49e336dfd9208",

   "value": "Sample"

6. Request data from KVStore:

INPUT

curl --request GET 'https://<hostname>/api/<tenant_id>/kvstore/Example' --header

'Authorization: Bearer <token>' -H "Content-Type: application/json"

OUTPUT

{

"_createdBy": "5fda253349a49e336dfd9226",

"_createdTs": 1618508904,

"_updatedBy": "5fda253349a49e336dfd9226",

"_updatedTs": 1618508904,

"_version": 1,

"changedBy": {

"apiKey": {

"exists": "exists",

"id": "6058bfa3fc8e031c30fdc913",

"name": "API_KEY_NAME"

},

"id": "5fda253349a49e336dfd9226",

"tenantId": "5fda253249a49e336dfd9208"

},

"id": "60787c68e106b5789efd921a",

"key": "Example",

"tenantId": "<tenant_id>",

"value": "Sample"

In Addition to the KVStore API, Machina 5.3 includes an easy-to-use user interface in the Machina Console. This allows admins to configure their partner integrations, like Google External Key Management (EKM) directly from the UI.

 

To configure your key value pairing in the UI

1. Log into Machina
2. Navigate to Settings
3. Select Key/Value Store
4. Select +Create Key/Value Pair

   

5. Add your Key Name
6. Add the associated value

   

7. Select Create

Tenant Search

Users who have multiple tenants are now able to search for specific Tenant IDs in order to connect to the correct console when attempting to login. This tenant lookup is based on the following items:

• Email address of the user
• Username
• External ID

Tenant ID in Dashboard

The Machina Tenant ID will now be revealed in the User Profiles section of the Machina Console.

Password Resets

When a Machina user requests a password reset, they will receive an email with a pre-populated URL for their registered email.

Console Enhancements

Key Requested State has been deprecated for our SaaS environment. This is now a Machina Terra only feature, which can be accessed via the CSA.

BETA FEATURES

Keyless Policy Decision

This feature is being added within the 5.3 release of the Machina Console as a beta feature for our Machina Saas customers only. This feature is fully tested, but relies on our KNS feature which may not be available for some Machina Terra (on-premises) customers. It allows for the streamlining of Machina as a Policy Decision Point (PDP) with a focus on utilizing the Machina platform beyond encryption with an emphasis on core technologies are Data Security from a central, externalized Policy control perspective. With Keyless Policy Decision, the client can provide context via the endpoint to allow policy driven decisions without the iteratives and overhead of key fetches.

This decision endpoint allows users to get a response to a request with a given set of contexts which can include:

• Action -> keyless decision
• Subject -> from details about this client/user
• Resource -> data, service or system component. A resource has one more or attributes Resource data is added by the client (i.e. classification, role, created group, etc.)
  • In case of key transactions, the "resource" is defined as the key. If a policy is being used to make a decision, it is assumed that it is being used to gate access to a resource. This leaves it up to the integrator to determine which attributes are appropriate for said resources, since the platform will not be explicitly aware of what the resource is.
• Env -> from metadata set on the request by Machina + data added by Ionic pips (eg. geoip lookip, device id, etc)

Customers can set any context that would ordinarily be supplied by a Machina key. That resource context can be set to a default value if not provided (if not provided, the default is empty). 

How to request a decision using Machina Keyless Policy Decision:

Prerequisites: Machina environment with configured policies in place set to Allow access when allow: true and deny in all other cases.

 

In this scenario, we are requesting a decision based upon the content of the

INPUT:

curl -X POST

"https://dashboard.deveng.ionic.engineering/5fda253249a49e336dfd9208/keyless" -H

"Content-Type: application/json" -H "Authorization: Bearer

NjA1OGJmYTNmYzhlMDMxYzMwZmRjOTEzopu+eHsDiysdXgNygcDSP8LrmDGvYM33TBzSfTv

B6RI=" -d '{"allow": true }

OUTPUT:

Request Denied:

{"response":"NotApplicable","status":"ok"}

 

Request Allowed:

{"response":"Permit","status":"ok"}

Keys Management API (aka Keys API)

Machina users no longer have to enroll devices in order to create or retrieve protections.

The Key Management API (KeysAPI) provides an alternative to existing Machina SDK functions which require devices to be enrolled to take advantage of the Machina Platform.

Keys API is a simple, language independent, VBE-less API that does not require and SDK to interface with Machina Platform.

This feature provides a more traditional approach to inter-operating with the Machina backend. This also allows the expansion of use cases where Machina SDKs may not be supported.

This API provides direct access to key management functions of Key Create and Key Fetch for authorized users of Machina. Please note that Key Modify is coming in a future release.

How to Enable/Disable KeysAPI

This feature is disabled by default.

NOTE: Must be a Tenant Admin

1. Log into Machina
2. Navigate to Settings
3. Select Machina Admin
4. Enable Keys API

   

How to Create Keys with KeysAPI

INPUT:

curl -X POST "https://<hostname>/v2.4/<keyspace_ID>/keys/create" -H "Content-

Type: application/json" -H"Authorization: Bearer <Token>" -d "{\"data\": {\"protectionkeys\":

[{\"qty\": 1, \"ref\": \"simple-request\"}]}}"

 

OUTPUT:

{

"cid": "CID|NONVBE|e25ba40d-60a4-4de2-41dc-

93704ac75f92|GSTp|1618510828471|2.4.0",

"data": {

"protection-keys": [

{

"csig": "3gr8t8yPKKxXvuRd2e5+JggItPbK0eEfHhqol98djU0=",

"id": "GSTpIrYsEV8",

"key":

"155f4de7d496223437cbdb3c9448ddff30e240dcd97dd9c8cdc5fcbba708f5d2",

"msig": "3gr8t8yPKKxXvuRd2e5+JggItPbK0eEfHhqol98djU0=",

"ref": "simple-request"

}

]

}

}

How to Fetch a Key With Keys API

INPUT:

curl -X POST "https://<hostname>/v2.4/<Keyspace_ID>/keys/fetch" -H "Content-

Type: application/json" -H "Authorization: Bearer

<Token>" -d "{\"data\": {\"protection-keys\":[\"GSTpIrYsEV8\"]}}"

 

OUTPUT:

{

"cid": "CID|NONVBE|01fbfb32-7145-40ab-7ab4-

00aa30ae4284|GSTp|1618511063496|2.4.0",

"data": {

"protection-keys": [

{

"csig": "3gr8t8yPKKxXvuRd2e5+JggItPbK0eEfHhqol98djU0=",

"id": "GSTpIrYsEV8",

"key":

"155f4de7d496223437cbdb3c9448ddff30e240dcd97dd9c8cdc5fcbba708f5d2",

"msig": "3gr8t8yPKKxXvuRd2e5+JggItPbK0eEfHhqol98djU0="

}

]

}

}

KNOWN ISSUES

N/A

BUG FIXES

• Role Based Access Controls (RBAC) did not always and properly work as intended. This resulted in some policy permissions being granted more or less access than intended.
• OAUTH logins were not being properly recorded under Login history.
• Policy create/rule builder dropdowns would scroll with the page.
• Customers were asked repeatedly to go through onboarding workflow even when 'Skip' has been selected by same user in the same browser.
• AppServer Logging issues addressed - In some customer environments, AppServers activity logs were not being properly sent to logstore.
• ExtID Key Modify Caching Fix - In certain situations, a key modify or creating a key under an existing external ID can result in a subsequent fetch returning unmodified results. With the 5.3 release, key modify requests or creating a key under an existing external ID will propagate through the system within 90 seconds (default) unless the cachettl config variable is set to another value. This value is configurable for Machina Terra Customers only.

Future Changes

In an effort to provide customers information in advance around features that we are planning to deprecate, we are adding this category to release notes. Here we will outline elements of Machina that we plan to deprecate in upcoming releases.

Machina Product Tab Deprecated

The product tab has been removed from the Machina Console Dashboard as the endpoint application portion of the console has also been deprecated.

The Product tab will be removed from the Machina Console Dashboard as the endpoint application portion of the console has also been deprecated. This will be removed in Machina 5.3 SaaS-1.