Initial public release.

Author: rmspeers

LICENSE.md

@@ -0,0 +1,42 @@
+# IONIC SOFTWARE LICENSE
+## 1. DEFINITIONS.  
+(a) “Derivative Work” shall mean a work that is based on one or more preexisting works, such as a revision, enhancement, modification, translation, abridgement, condensation, expansion, or any other form in which such preexisting works may be recast, transformed, or adapted, and that, if prepared without authorization of the owner in the copyright in such preexisting work, would constitute a copyright infringement, and specifically shall include any compilation that incorporates such a preexisting work.  
+
+(b) “Services” shall mean Ionic’s data protection and access control platform and related services provided by Ionic in the ordinary business course.  
+
+(c) “Software” means the application programming interfaces that enable You or Your applications to interface, interoperate or interconnect with the Services, or other original works of authorship, whether in source or object code form, that are made available under this License by including in or with such work either (i) a copyright notice referencing the applicability of this License, or (ii) a copy of this License.  
+ 
+(d) “You” means any individual or corporation, partnership, limited liability company, trust, association or other entity or organization, including any governmental or political subdivision or any agency or instrumentality thereof, exercising rights or permissions granted by this License.  
+
+## 2. GRANT OF LICENSE.  
+(a) Subject to the terms and conditions of this License, Ionic grants to You a perpetual, worldwide, non-exclusive, royalty-free, copyright license to prepare Derivative Works of, reproduce, publicly display, publicly perform, sublicense and distribute the Software and any resulting Derivative Works in any form.  
+
+(b) Subject to the terms and conditions of this License, Ionic grants to You a perpetual, worldwide, non-exclusive, royalty-free patent license to make, have made, use, sell, offer for sale, import, and otherwise transfer its Software licensed under this License, in whole or in part. The foregoing license applies only to the patent claims that would be infringed by Ionic’s Software individually and expressly excludes any combinations with any other materials or technology.  
+
+(c) There is no license fee for the Software.  
+
+## 3. LIMITATIONS.  
+(a) Redistribution. You may reproduce or distribute the Software only if You (i) do so pursuant to this License, (b) include a complete copy of this License with Your distribution, and (c) retain without modification any copyright, patent, trademark, or other notices that are present in the Software.  
+
+(b) Derivative Works. You may specify that additional or different license or othere terms apply to the use, reproduction, and distribution of your Derivative Works provided that (i) Your terms provide do not supersede, replace or modify the redistribution rights set forth in Section 3(a) above, (ii) Your terms provide that the use limitation in Section 3(c) below applies, and (iii) You identify the specific Derivative Works that are subject to Your terms.  
+
+(c) Use Limitation. The Software and any Derivative Works may be used or intended for use only with the Services, platforms applications provided by Ionic or its affiliates.  
+
+(d) Trademarks. This License does not grant any rights to use any of Ionic’s or its affiliates’ names, logos, or trademarks, except as necessary to reproduce the notices and legends as set forth in this License.  
+
+(e) Termination. If You violate any term of this License, then Your rights under this License will terminate immediately. In addition, if You bring or threaten to bring a patent claim against Ionic to enforce any patents that you allege are infringed by the Software, then your rights under this License may be terminated immediately by Ionic.  
+
+## 4. DISCLAIMER OF WARRANTIES.  
+THE SOFTWARE IS PROVIDED “AS IS,” WITHOUT ANY WARRANTY WHAT¬SO¬EVER, AND THIS LICENSE EXCLUDES, AND IONIC SPECIFICALLY DISCLAIMS, ALL EXPRESS, IMPLIED OR STATUTORY REPRESENTATIONS OR WARRANTIES WITH RESPECT TO THE SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANT¬ABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. YOU BEAR THE RISK OF UNDERTAKING ANY ACTIVITIES UNDER THIS LICENSE.  
+
+## 5. LIMITATION OF LIABILITY
+EXCEPT WHERE PROHIBITED BY LAW, IN NO EVENT SHALL IONIC BE LIABLE UNDER ANY CONTRACT, WARRANTY, NEGLIGENCE, STRICT LIABILITY OR OTHER LEGAL OR EQUITABLE THEORY FOR LOSS OR CORRUP¬TION OF DATA, LOSS OF BUSINESS PROFITS, BUSINESS INTERRUP¬TION, LOSSES RESULTING FROM SYSTEM SHUTDOWN, FAILURE TO ACCURATELY TRANSFER, READ OR TRANSMIT INFORMA¬TION, SYSTEM INCOMPATIBILITY OR PROVIDING INCORRECT COMPATIBILITY INFORMATION, OR SPECIAL, PUNITIVE, INCIDENTAL, CONSEQUENTIAL OR INDIRECT DAMAGES RESULTING FROM THE LICENSING, FURNISHING, PERFOR¬MANCE OR USE OF THE LICENSED TECHNOLOGY, EVEN IF IONIC HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE, AND NOTWITHSTANDING ANY FAILURE OF ESSENTIAL PURPOSE OF ANY REMEDY ARISING OUT OF OR IN CONNECTION WITH THIS AGREEMENT.  
+
+## 6. COMPLETE AGREEMENT.  
+This License constitutes the complete and exclusive statement of the agreement among the parties hereto concerning the subject matter hereof.  It supersedes all prior written and oral statements, including any prior representation, statement, condition or warranty.  
+
+## 7. APPLICABLE LAW.  
+This Agreement will be governed by, and construed in accordance with the laws of the State of Georgia, U.S.A.  
+
+Effective Date: November 3, 2017
+

README.md

@@ -1,2 +1,52 @@
-# ionic-devreq-api-python
-Example Python Code for Interacting with Ionic's Device Request API
+# ionic-devreq-api-python: Example Code for Interacting with Ionic's Device Request API
+
+## Explanation
+
+This example code shows how to use the advanced Device Request APIs available from the Ionic Platform.
+It is meant to serve as sample code for developers learning about those APIs to use as reference.
+
+Most developers will instead prefer to use Ionic's supported SDKs, which include a Python SDK which has the same
+ functionality shown in these examples, as well as significant additional features.
+
+## Setting up Environment
+
+You may want to use Python's virtualenv toolkit to manage your environment.
+
+Once loaded, install the pre-requisites:
+```bash
+pip install -r requirements.txt
+```
+
+## Running Examples
+
+### Create and Fetch Keys:
+
+The `example.py` tool shows how to create keys, and then request them again.
+These two operations are usually done independently.
+
+Using this example requires a Secure Enrollment Profile (SEP), which it expects via the plaintext profile persistor in a file `profiles.pt`.
+Read [Enrollment Overview](https://dev.ionic.com/registration.html) to learn more.
+See the Enrollment Example for obtaining one if you don't have one via another mechanism.
+
+### Enrolling:
+
+The `example_enroll.py` tool shows enrolling a device and obtaining a SEP, and then storing it using the plaintext profile persistor.
+
+Using this example requires first editing the code to define the correct values for the variables.
+After setting those values, it can be run and will produce `profiles.pt` which is the SEP stored in plaintext.
+
+There are two options for setting the values:
+
+#### Provide Username/Password for Ionic IdP-linked Enrollment Servers
+
+If, and only if, your enrollment server is linked to Ionic's IdP (which is only for development/demo environments), then
+ you can enter your Ionic username and password in the file (for demonstration purposes only) and it will obtain the
+ stoken/uidauth values for you.
+
+#### Provide stoken/uidauth Obtained from Any Enrollment Method
+
+These values are typically obtained from doing the workflows described in [Enrollment Overview](https://dev.ionic.com/registration.html),
+ such as SAML, Oauth, email token, or generated SAML assertions.
+You will need to perform the communication with the enrollment server, following the process for your selected
+ enrollment type, to obtain these values before entering them and then running this script. 
+See `registration/get_ionic_token.py` for an example of doing this for a SAML enrollment against the demonstration Ionic IdP.

__init__.py

@@ -0,0 +1,17 @@
+############################################################
+# This is a code sample for the Ionic Security Inc. API,   #
+# and this packages it so it is usable by other examples.  #
+# The intention is to show how to interact with the API    #
+# using builtin and 3rd-party libraries instead of the     #
+# Ionic SDK.                                               #
+#                                                          #
+# (c) 2017 Ionic Security Inc.                             #
+# Confidential and Proprietary                             #
+# By using this code, I agree to the Terms & Conditions    #
+#  (https://www.ionic.com/terms-of-use/) and the Privacy   #
+#  Policy (https://www.ionic.com/privacy-notice/)          #
+############################################################
+
+from registration.registration import create_device
+from keys.keys import create_keys, fetch_keys
+import persistors.persistors

example.py

@@ -0,0 +1,54 @@
+###########################################################
+# This is a code sample for the Ionic Security Inc. API,  #
+# It assumes a SEP and usage v2.3 of the API              #
+# The intention is to show how to interact with the API   #
+# using built-in and 3rd-party libraries instead of the   #
+# Ionic SDK.                                              #
+#                                                         #
+# This example uses Python 3.4.3                          #
+# This example is best read with syntax highlighting on.  #
+#                                                         #
+# (c) 2017 Ionic Security Inc.                            #
+# Confidential and Proprietary                            #
+# By using this code, I agree to the Terms & Conditions   #
+#  (https://www.ionic.com/terms-of-use/) and the Privacy  #
+#  Policy (https://www.ionic.com/privacy-notice/)         #
+# Author = rmspeers, QA =                                 #
+###########################################################
+
+from keys import create_keys, fetch_keys
+from persistors import ProfilePersistorPlaintext
+
+####################################################
+### Requires a Device Secure Enrollment Profile  ###
+####################################################
+# Assume a SEP saved to a file named `profiles.pt` #
+# which contains a plaintext SEP for demo purposes #
+# only. Use a different persistor type in real use.#
+####################################################
+
+
+if __name__ == "__main__":
+    persistor = ProfilePersistorPlaintext('profiles.pt')
+    ionic_sep = persistor.get_active_profile()
+
+    # Best practice is to include key attributes to describe the type of data you will be using this key to protect:
+    ## These can either be `ionic-protected-*` prefixed so Ionic.com can't see them, and only other requestors who
+    ##  access the key can; or they can be unencrypted so that Ionic.com can use their values in policy decisions.
+    dictKeyAttrs = {
+        'classification': 'Public',
+        'ionic-protected-test': ['encrypted_value_1']
+    }
+    created_keys = create_keys(ionic_sep, dictKeyAttrs)
+    print('Created keys: {}'.format(created_keys))
+
+    # Now we show fetching one of these keys back:
+    # NOTE: We may or may not be able to get it depending on the current data policy.
+    print('Requesting the following keys by ID: {}'.format(', '.join(created_keys.keys())))
+
+    # The value is a JSON object with a field "protection-keys" containing
+    # an array of keytag strings. An example of the protection_keys array:
+    # protection_keys = ["ABcdGadsg23", "ABcdGP34erq"]
+    # See `example_external_ids.py` for another way to retrieve keys.
+    fetched_keys = fetch_keys(ionic_sep, list(created_keys.keys()))
+    print('Retrieved keys: {}'.format(fetched_keys))

example_enroll.py

@@ -0,0 +1,73 @@
+###########################################################
+# This is a code sample for the Ionic Security Inc. API,  #
+# It assumes a SEP and usage v2.3 of the API              #
+# The intention is to show how to interact with the API   #
+# using built-in and 3rd-party libraries instead of the   #
+# Ionic SDK.                                              #
+#                                                         #
+# This example uses Python 3.4.3                          #
+# This example is best read with syntax highlighting on.  #
+#                                                         #
+# (c) 2017 Ionic Security Inc.                            #
+# Confidential and Proprietary                            #
+# By using this code, I agree to the Terms & Conditions   #
+#  (https://www.ionic.com/terms-of-use/) and the Privacy  #
+#  Policy (https://www.ionic.com/privacy-notice/)         #
+# Author = rmspeers, QA = jmassey                         #
+###########################################################
+
+import sys
+
+from registration import create_device
+from registration import get_ionic_token
+from persistors import ProfilePersistorPlaintext
+
+####################################################
+### Creates a Device Secure Enrollment Profile   ###
+####################################################
+# It will output SEP to a file named `profiles.pt` #
+# which contains a plaintext SEP for demo purposes #
+# only. Use a different persistor type in real use.#
+####################################################
+
+# TODO:
+# If you are using Ionic's IdP, you can enter your username
+# and password below. If not, you must obtain a UIDAUTH
+# and STOKEN before registering. These must be unique to each
+# registration to prevent replay attacks. 
+
+user = ""
+password = r""
+
+stoken = ""
+uidauth = ""
+
+api_url = "https://dev-api.ionic.com"
+enrollment_server_url = "https://dev-enrollment.ionic.com"
+keyspace = "ABcd"
+
+
+if __name__ == "__main__":
+    # Validate the user provided input:
+    if api_url == "" or enrollment_server_url == "" or keyspace == "":
+        print("ERROR: api_url, enrollment_server_url, and keyspace must all be defined.")
+        sys.exit(1)
+    if user != "" and password != "":
+        enrollment_url = "{}/keyspace/{}/register".format(enrollment_server_url, keyspace)
+        stoken, uidauth = get_ionic_token(enrollment_url, user, password)
+    if stoken == "" or uidauth == "":
+        print("ERROR: Username and Password or STOKEN and UIDAUTH must be defined")
+        sys.exit(2)
+
+    # Generate the request body, make the request, and decrypt the responses from the key server and Ionic.com
+    sep = create_device(api_url, keyspace, enrollment_server_url, stoken, uidauth)
+    # Display the profile received
+    print(sep)
+
+    # Save the profile to a file
+    # NOTE: This will overwrite any existing content at that path.
+    persistor = ProfilePersistorPlaintext()
+    persistor.add_sep(sep, set_as_active=True)
+    persistor.set_file_path("profiles.pt")
+    print(persistor)
+    persistor.save_to_json()

example_external_ids.py

@@ -0,0 +1,61 @@
+###########################################################
+# This is a code sample for the Ionic Security Inc. API,  #
+# It assumes a SEP and usage v2.3 of the API              #
+# The intention is to show how to interact with the API   #
+# using built-in and 3rd-party libraries instead of the   #
+# Ionic SDK.                                              #
+#                                                         #
+# This example uses Python 3.4.3                          #
+# This example is best read with syntax highlighting on.  #
+#                                                         #
+# (c) 2017 Ionic Security Inc.                            #
+# Confidential and Proprietary                            #
+# By using this code, I agree to the Terms & Conditions   #
+#  (https://www.ionic.com/terms-of-use/) and the Privacy  #
+#  Policy (https://www.ionic.com/privacy-notice/)         #
+# Author = rmspeers, QA =                                 #
+###########################################################
+
+from uuid import uuid4
+
+from keys import create_keys, fetch_keys
+from persistors import ProfilePersistorPlaintext
+
+####################################################
+### Requires a Device Secure Enrollment Profile  ###
+####################################################
+# Assume a SEP saved to a file named `profiles.pt` #
+# which contains a plaintext SEP for demo purposes #
+# only. Use a different persistor type in real use.#
+####################################################
+
+if __name__ == "__main__":
+    persistor = ProfilePersistorPlaintext('profiles.pt')
+    ionic_sep = persistor.get_active_profile()
+
+    # We generate, via whatever method, an external ID which allows us an alternate way to query for the key.
+    external_id = uuid4().hex
+    print('We will be referencing: {}'.format(external_id))
+
+    # Best practice is to include key attributes to describe the type of data you will be using it to protect:
+    # See `example.py` for other options, including using encrypted attributes.
+    dictKeyAttrs = {'classification': 'Public'}
+    dictKeyAttrs["ionic-external-id"] = [external_id]
+
+    created_keys = create_keys(ionic_sep, dictKeyAttrs)
+    print('Created keys: {}'.format(created_keys))
+
+    # Now we show fetching these keys back, using the external ID _instead of the key ID_:
+    # NOTE: We may or may not be able to get it depending on the current data policy.
+    print('We could request these keys by ID: {}'.format(', '.join(created_keys.keys())))
+
+    # The value is a JSON object with a field "protection-keys" containing
+    # an array of keytag strings. An example of the protection_keys array:
+    # protection_keys = ["ABcdGadsg23", "ABcdGP34erq"]
+    print('However instead we will query for the key by the external ID we gave it: {}'.format(external_id))
+    protection_keys = []            # Can define to an empty array if only want to query by external_ids.
+    external_ids = [external_id]    # Can define to None if only want to query by key IDs (as is typical).
+    decrypted_keys, query_results = fetch_keys(ionic_sep, protection_keys, external_ids=external_ids)
+    print('Fetch keys: {}'.format(decrypted_keys))
+    if query_results is not None:
+        print('Query results: {}'.format(query_results))

keys/__init__.py

@@ -0,0 +1,16 @@
+############################################################
+# This is a code sample for the Ionic Security Inc. API,   #
+# and this packages it so it is usable by other examples.  #
+# The intention is to show how to interact with the API    #
+# using builtin and 3rd-party libraries instead of the     #
+# Ionic SDK.                                               #
+#                                                          #
+# (c) 2017 Ionic Security Inc.                             #
+# Confidential and Proprietary                             #
+# By using this code, I agree to the Terms & Conditions    #
+#  (https://www.ionic.com/terms-of-use/) and the Privacy   #
+#  Policy (https://www.ionic.com/privacy-notice/)          #
+############################################################
+
+from keys.key_create import create_keys
+from keys.key_fetch import fetch_keys