From c02daf609f38ae37de87dc8c132d9fc1284b8152 Mon Sep 17 00:00:00 2001 From: Rick Ehrhart Date: Fri, 7 Aug 2020 09:39:51 -0700 Subject: [PATCH] Removed local decrypt_envelop(). Updated assert for HTTP error. Updated python libraries. Updated README.md. Updated copyright. --- LICENSE.md | 79 ++++++++--------------- README.md | 26 +++++--- __init__.py | 2 +- example.py | 13 ++-- example_enroll.py | 15 +++-- example_external_ids.py | 5 +- keys/__init__.py | 2 +- keys/key_create.py | 10 +-- keys/key_fetch.py | 55 +++------------- keys/utilities.py | 22 +++++-- persistors/__init__.py | 2 +- persistors/profile.py | 5 +- persistors/profile_persistor_plaintext.py | 5 +- registration/__init__.py | 2 +- registration/get_ionic_token.py | 8 ++- registration/register.py | 5 +- requirements.txt | 22 +++---- 17 files changed, 118 insertions(+), 160 deletions(-) diff --git a/LICENSE.md b/LICENSE.md index 44b1fd7..5a07222 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,69 +1,42 @@ -# License Agreement for Ionic Resources +# 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. -Please read the following terms and conditions (the “Agreement”) carefully and completely. This Agreement grants a license to the Ionic Security Inc. (“Ionic”) resources accompanying or associated with this Agreement (“Ionic Resources”) which can be used to interact with the Ionic data security and access control platform and related key management servers (“Platform”). The Ionic Resources comprise Ionic applications, plug-in components, end point components, software development kits (“SDKs”) and any associated tools, libraries, code samples, and toolkits (collectively, the “Software”; Software provided by Ionic in source code format is the “Source Code”) and associated documentation, if any (“Software Documentation”). The Ionic Resources expressly exclude any documentation for Ionic API’s which are subject to the separate Documentation User Rights. Ionic Resources not including any Source Code are the “Restricted Ionic Resources”. +(b) “Services” shall mean Ionic’s data protection and access control platform and related services provided by Ionic in the ordinary business course. -IF YOU ARE ENTERING INTO THIS AGREEMENT ON BEHALF OF A COMPANY, GOVERNMENT AGENCY, ASSOCIATION OR OTHER LEGAL ENTITY (IN WHICH CASE THE TERMS "YOU" OR "YOUR" SHALL REFER TO SUCH ENTITY AND ITS AFFILIATES), YOU HEREBY REPRESENT AND WARRANT THAT YOU HAVE THE POWER AND AUTHORITY TO ENTER INTO THIS AGREEMENT ON SUCH ENTITY’S BEHALF AND TO BIND SUCH ENTITY AND ITS AFFILIATES HERETO. +(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. -**1. LICENSE; RESTRICTIONS.** -1.1 Subject to the terms and conditions of this Agreement, Ionic grants to you a non-exclusive, worldwide (except as restricted herein), non-transferable, non-sublicensable, revocable right and license to (i) make derivative works of any Software provided by Ionic in source code format (“Derivative Works”; the Derivative Works and Ionic Resources cumulatively, the “Resources”), (ii) reproduce as reasonably necessary, install and use the Software and Derivative Works in a non-production environment to test the Software and Derivative Works, (iii) redistribute Source Code in its original source code format on the condition that it is redistributed under this Agreement and a copy of this Agreement is included with each copy of the Source Code and (iv) reproduce as reasonably necessary and use the Software Documentation to support the rights granted in 1.1(i) and (ii). For clarity, you are not licensed to redistribute any Restricted Ionic Resources or distribute any Derivative Works. +## 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. -1.2 If you have been granted the authority to access and use the Platform pursuant to one or more agreements entered into between Ionic and the company, government agency, association or other entity you represent (the “Master Agreement”) then subject to the terms and conditions of this Agreement, Ionic grants to you a non-exclusive, worldwide (except as restricted herein), non-transferable, non-sublicensable, revocable right and license (i) to install and use the object code version of the Software and Derivative Works to interconnect with the Platform and exchange information for your internal business purposes pursuant to the terms and conditions of the Master Agreement during the term of the Master Agreement and (ii) to reproduce as reasonably necessary and use the Software Documentation to support the rights granted in 1.2(i). +(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. -1.3 The licenses set forth in Sections 1.1 and 1.2 also include the right for you to allow affiliates and contractors to access and use the Resources solely to assist you in performing activities within the scope of the rights granted in Section 1.1 and 1.2 for your benefit. You are responsible for the acts of your affiliates and contractors as if such acts were taken by you. +(c) There is no license fee for the Software. -1.4 You agree that you will not (and will not permit any third party to) directly or indirectly: (i) use, reproduce or distribute the Resources in any manner inconsistent with the license grants set forth in this Agreement; (ii) decompile, disassemble, reverse engineer or otherwise attempt to reconstruct or discover any source code, algorithms or formulae of any Software that is not Source Code; (iii) use or allow others to use or commercially exploit the Resources to or for the benefit of any third party; (iv) remove any product identification, copyright or other proprietary notice from the Resources; or (v) otherwise engage in any activity that interferes with, disrupts, damages, or accesses in an unauthorized manner the Platform, or any servers, networks, data or other properties of Ionic. +## 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. -**2. REPRESENTATIONS & WARRANTIES** -2.1 You acknowledge that the Resources contain cryptographic features and may be subject to United States laws governing import, export, distribution and use, including the Export Administration Act of 1979, as amended, any successor legislation, and the Export Administration Regulations issued by the Department of Commerce, International Trade Administration, and Bureau of Export Administration (collectively, the “EAR”). You agree to comply in all respects with the export and re-export restrictions applicable to the Resources and otherwise comply with the EAR or other U.S. laws and regulations in effect from time to time. You will not export or re-export the Resources, directly or indirectly, to: (1) any countries that are subject to U.S. export restrictions (currently including, but not necessarily limited to, Cuba, Iran, North Korea, Sudan, and Syria); or (2) any end user who (i) you know or have reason to know will utilize them in the design, development or production of nuclear, chemical or biological weapons, or rocket systems, space launch vehicles, or sounding rockets, or unmanned air vehicle systems, or (ii) is designated on the U.S. Treasury Department list of Specially Designated Nationals (“Denied Persons List”) or the U.S. Commerce Department's Table of Deny Orders or who has been otherwise prohibited from participating in U.S. export transactions by any federal agency of the U.S. government ((2)(i) and (ii) collectively, a “Denied Person”). You also represent that you are not a Denied Person and consent to Ionic checking you against the Denied Persons List prior to accepting this Agreement or granting you access to the Ionic Resources and from time to time as may be required by applicable law. +(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. -2.2 If you are or any affiliate of yours is the U.S. Federal Government, Ionic provides the Ionic Resources solely in accordance with the term of this Section 2.2. Government technical data and software rights related to the Ionic Resources include only those rights customarily provided to the public as defined in this Agreement. This customary license is provided in accordance with FAR 12.211 (Technical Data) and FAR 12.212 (Software) and, for Department of Defense transactions, DFAR 252.227-7015 (Technical Data – Commercial Items) and DFAR 227.7202-3 (Rights in Commercial Computer Software or Computer Software Documentation). If a government agency has a need for rights not conveyed under these terms, it must negotiate with Ionic directly to determine if there are acceptable terms for transferring such rights, and a mutually acceptable written addendum specifically conveying such rights must be included in any applicable agreements. +(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. -**3. MODIFICATIONS.** -You acknowledge and agree that Ionic may modify this Agreement by making a revised version available at http://dev.ionic.com. Your continued access to and use of the Ionic Resources after the revised version is available at http://dev.ionic.com shall constitute your binding acceptance of such modifications. +(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. -**4. OWNERSHIP; IP RIGHTS.** -4.1 As between you and Ionic, Ionic owns exclusively and will retain ownership of all right, title, and interest in and to the Ionic Resources, and you will own the Derivative Works to the extent comprising changes and modifications to the Software made by or for you. Subject to the limited rights and licenses expressly provided in this Agreement, nothing herein shall be deemed to convey, transfer or assign to you or any of your affiliates any intellectual property rights of Ionic. +(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.2 You understand that Ionic may license certain software packages, libraries or components of the Software under an open source software license. You understand and acknowledge that your use, reproduction and distribution of any such open source components are governed solely by the terms of the applicable open source software license and not this Agreement. If there are any conflicts between the open source software license and this Agreement, the open source license terms control. +## 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. ACCESS TO PLATFORM; APPLICATION SUPPORT.** -This Agreement does not entitle you to access the Ionic Platform. Such access is governed by the Master Agreement. +## 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. CONFIDENTIALITY.** -6.1 The Restricted Ionic Resources and any information developed in exercising rights granted in the Agreement and related to the performance, features, functionality, fees and usability of the Software and the Platform (cumulatively, the “Ionic Information”) is the proprietary and confidential information of Ionic, except as otherwise expressly stated herein or agreed in writing by Ionic. You will maintain the Ionic Information as proprietary and confidential, and will use the same level of care, but no less than a reasonable level of care, to prevent the unauthorized use, dissemination, or publication of the same as you use to protect your own proprietary and confidential information. The obligations of confidentiality required by this paragraph shall extend, for any Ionic Information that constitutes a Trade Secret (as defined below), so long as such information remains a Trade Secret, and for any Ionic Information that does not constitute a Trade Secret, for a period of three (3) years after the termination of this Agreement. As used herein, “Trade Secrets” means information which derives economic value, actual or potential, from not being generally known to, and not being readily ascertainable by proper means by, other persons who can obtain economic value from its disclosure or use, and is the subject of efforts that are reasonable under the circumstances to maintain its secrecy, including, without limitation, the Software specifications and technical documentation, and any underlying ideas, algorithms, or structure, technical or nontechnical data, formulas, patterns, compilations, programs, devices, methods, techniques, drawings, processes, financial data, financial plans, or product plans. +## 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. -6.2 Notwithstanding the foregoing, the obligations of confidentiality required by this Section 6 shall not cover information that (a) was already known to you at the time of disclosure by or on behalf of Ionic without an obligation of confidentiality; (b) was or is obtained by the recipient from a third party not under an obligation of confidentiality with respect to such information; (c) is or becomes generally available to the public other than by violation of an agreement; or (d) was or is independently developed by you without use of the Ionic Information. +## 7. APPLICABLE LAW. +This Agreement will be governed by, and construed in accordance with the laws of the State of Georgia, U.S.A. -**7. DISCLAIMER OF WARRANTIES.** -THE IONIC RESOURCES ARE PROVIDED ON AN AS IS AND AS AVAILABLE BASIS, WITHOUT ANY WARRANTIES OF ANY KIND. TO THE MAXIMUM EXTENT ALLOWED UNDER APPLICABLE LAW, NEITHER IONIC NOR ITS LICENSORS OR SUBCONTRACTORS MAKES ANY WARRANTY, EXPRESS, IMPLIED OR STATUTORY, REGARDING THE IONIC RESOURCES. IONIC AND ITS LICENSORS AND SUBCONTRACTORS EXPRESSLY EXCLUDE ANY IMPLIED WARRANTY OF NON-INFRINGEMENT, FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY AND ANY OTHER WARRANTY THAT MIGHT ARISE FROM COURSE OF DEALING OR USAGE OF TRADE REGARDING THE IONIC RESOURCES. WITHOUT LIMITING THE GENERALITY OF THE FOREGOING, IONIC DOES NOT REPRESENT OR WARRANT THAT THE RESOURCES WILL OPERATE IN COMBINATION WITH ANY OF YOUR APPLICATIONS OR ANY OTHER HARDWARE, SOFTWARE, SYSTEM OR DATA. THE SOFTWARE AND DERIVATIVE WORKS MAY BE SUBJECT TO LIMITATIONS, DELAYS, AND OTHER PROBLEMS INHERENT IN THE USE OF THE INTERNET AND ELECTRONIC COMMUNICATIONS THAT ARE PROVIDED BY THIRD PARTIES OTHER THAN IONIC OR ITS SUBCONTRACTORS, AND IONIC IS NOT RESPONSIBLE FOR ANY DELAYS, DELIVERY FAILURES, OR OTHER DAMAGES RESULTING FROM SUCH PROBLEMS. +Effective Date: November 3, 2017 -**8. INDEMNIFICATION.** -8.1 Ionic will defend (including paying reasonable and actual attorneys’ fees and court costs) you and your respective officers, directors, employees, and agents (“Indemnified Entities”) from and against any third party claim that your use of the Ionic Resources as licensed hereunder and in accordance with any applicable Software Documentation during any time that you were a party to a valid Master Agreement infringes, misappropriates or otherwise violates the intellectual property rights of such third party and will indemnify and hold harmless the Indemnified Entities from any final, non-appealable judgments or settlement expenses resulting from such a claim, provided that you (a) promptly notify Ionic in writing of such claim, (b) permit Ionic to control of the defense and settlement of the claim, and (c) provide Ionic, at its expense, reasonable assistance as required for the defense and settlement of such claim. Ionic will have no liability for any claim to the extent that it results from: (i) any modification to the Software made by a party other than Ionic, if a claim would not have occurred but for such modification; (ii) the combination, operation or use of the Software with any hardware, software, systems or data of any third party, if a claim would not have occurred but for such combination, operation or use; or (iii) your failure to use the latest version of the Software. - -8.2 You will indemnify and hold Ionic, its officers, directors, employees, and agents harmless from and against any and all losses, costs, damages, expenses and liabilities (including reasonable and actual attorneys’ fees and court costs) arising from or related to: (a) your use of the Ionic Resources other than strictly in accordance with any applicable Software Documentation which infringes, misappropriates or otherwise violates any third party intellectual property rights; (b) any breach of an obligation, representation, warranty, covenant or other provision of this Agreement by you or your affiliates or (c) any matter which you have expressly agreed to be responsible pursuant to this Agreement, provided that Ionic promptly notifies you of such claim. - -**9. LIMITATION OF LIABILITY.** -9.1 IONIC AND ITS DIRECTORS, OFFICERS, EMPLOYEES AND AGENTS SHALL NOT BE LIABLE FOR ANY CONSEQUENTIAL, INCIDENTAL, INDIRECT, SPECIAL, EXEMPLARY AND/OR PUNITIVE DAMAGES (EXCEPT WITH REGARD TO PUNITIVE DAMAGES WHICH MAY NOT BE EXCLUDABLE IN THE RELEVANT JURISDICTION), INCLUDING DAMAGES FOR LOST PROFITS, LOSS OF DATA, CORRUPTION OF DATA, OR LOSS OF BUSINESS IN CONNECTION WITH THE RESOURCES OR OTHERWISE UNDER THIS AGREEMENT, REGARDLESS OF THE FORM OF THE ACTION OR THE THEORY OF RECOVERY, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -9.2 NOTWITHSTANDING ANYTHING TO THE CONTRARY IN THIS AGREEMENT, IN NO EVENT SHALL IONIC, ITS DIRECTORS, OFFICERS, EMPLOYEES, OR AGENTS BE LIABLE TO YOU OR ANY THIRD PARTY IN CONNECTION WITH THE RESOURCES, OR OTHERWISE HEREUNDER FOR AN AMOUNT GREATER THAN ONE HUNDRED U.S. DOLLARS ($100.00). Some jurisdictions do not allow the exclusion of implied warranties or limitation of liability for incidental or consequential damages, which means that some of the above limitations may not apply to you. IN THESE JURISDICTIONS, THE COMPANY'S LIABILITY WILL BE LIMITED TO THE GREATEST EXTENT PERMITTED BY LAW. - -Notwithstanding the foregoing, the limitations of liability set forth in Sections 9.1 and 9.2 (a) shall not limit either party's indemnification obligations as specified in Section 8 and (b) shall not apply to either party's liability resulting from (i) personal injury, death or tangible property damages resulting from the party's gross negligence or willful misconduct or (ii) a breach of your confidentiality obligations set forth in Section 6. - -**10. TERM AND TERMINATION.** -This Agreement shall commence on the effective date hereof and will remain in effect until terminated pursuant to this Section 10. Either party may terminate this Agreement at any time for convenience upon notice. Any termination of this Agreement shall also terminate the licenses granted to you hereunder. Upon termination of this Agreement for any reason, you shall cease using, and either return to Ionic, or destroy and remove from all computers, hard drives, networks, and other storage media, all copies of the Ionic Resources. The provisions of this Agreement pertaining to ownership of the Resources, intellectual property, confidential information, disclaimer of warranties, exclusion of damages, indemnity, and miscellaneous issues shall survive any termination of this Agreement for any reason. - -**11. MISCELLANEOUS.** -11.1 This Agreement, together with the Master Agreement and any other guidelines, terms of use or policies as Ionic may from time to time adopt and publish, constitutes the entire understanding between you and Ionic with respect to the Ionic Resources, and supersedes all prior and collateral communications, reports, and understandings between you and Ionic in respect thereto; provided, however, that in the event of any conflict between this Agreement and the Master Agreement, the terms of the Master Agreement will control. - -11.2 The parties understand and agree that the mutual promises and covenants of this Agreement are special, unique, and of extraordinary character, and in the event of any default, breach, or threatened breach of this Agreement by you, Ionic shall be entitled, at its sole discretion, to institute proceedings in any court of competent jurisdiction, either at law or in equity, and shall be entitled to any and all such remedies (including any damages, injunctive relief, or combination thereof) as may be available at law or in equity. - -11.3 Except as set forth in Section 3 above, no change, modification, alteration, or addition to, or any waiver of, any provision of this Agreement shall be binding unless in writing and executed by authorized representatives of both you and Ionic. No waiver of any provision of this Agreement shall render unenforceable any other provision of this Agreement. - -11.4 In the event that any provision of this Agreement is held void, voidable, invalid, or inoperative, no other provision of this Agreement shall be affected as a result thereof, and the remaining provisions of this Agreement shall remain in full force and effect. - -11.5 This Agreement shall be governed by and interpreted in accordance with the laws of the State of Georgia, United States of America, without giving effect to any conflicts of laws principles. All disputes arising out of this Agreement will be subject to the exclusive jurisdiction and venue of the state courts located in Fulton County, Georgia and the federal courts located in the Northern District of Georgia, and each Party hereby consents to the personal jurisdiction thereof. - -11.6 All notices to be provided by Ionic to you under this Agreement may be delivered in writing: (i) by nationally recognized overnight delivery service or U.S. Mail to any contact mailing address provided by you; or (ii) by electronic mail to the electronic mail address provided by you. All notices to be provided by you to Ionic hereunder must be delivered in writing by nationally recognized overnight delivery service or U.S. Mail to the following address: Ionic Security Inc., 1170 Peachtree St., NE, Suite 400, Atlanta, GA 30309 USA, Attn: Chief Legal Counsel, or by electronic mail to legal@ionicsecurity.com. All notices shall be deemed to have been given immediately upon delivery by confirmed electronic mail, or if otherwise delivered upon receipt or, if earlier, two (2) business days after being deposited in the mail or with a Courier as permitted above. - - -Last updated 04/23/2018 diff --git a/README.md b/README.md index b109da4..37cb408 100644 --- a/README.md +++ b/README.md @@ -2,18 +2,24 @@ ## Explanation -This example code shows how to use the advanced Device Request APIs available from the Ionic Platform. +This example code shows how to use the advanced [Device Request APIs](https://dev.ionic.com/api/device) available from the Machina 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. +Most developers will instead prefer to use [Ionic's supported SDK](https://dev.ionic.com/sdk/features), which include a Python SDK which has the same + functionality shown in these examples, as well as significant additional features. There are SDK examples for [Create Key](https://dev.ionic.com/sdk/tasks/create-key?language=python) and [Get Key](https://dev.ionic.com/sdk/tasks/get-key?language=python). ## Setting up Environment +You will need to obtain a tenant. A free tenant can be obtained [here](https://ionic.com/start-for-free/). By following the prompted path, your +device will be enrolled. + +## Setting up Development 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 ``` @@ -21,19 +27,21 @@ pip install -r requirements.txt ### Create and Fetch Keys: -The `example.py` tool shows how to create keys, and then request them again. +The `example.py` sample 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`. +Using this example requires a Secure Enrollment Profile (SEP), which it expects via the plaintext profile persistor in a file `$HOME/.ionicsecurity/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. +See **Enrolling** below if you didn't enroll via another mechanism. + +This example shows how to use the [Create Key API](https://dev.ionic.com/api/device/create-key) and the [Get Key API](https://dev.ionic.com/api/device/get-key). -### Enrolling: +### 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. +After setting those values, it can be run and will produce `$HOME/.ionicsecurity/profiles.pt` which is the SEP stored in plaintext. There are two options for setting the values: diff --git a/__init__.py b/__init__.py index 0321118..34b9cfc 100644 --- a/__init__.py +++ b/__init__.py @@ -5,7 +5,7 @@ # using builtin and 3rd-party libraries instead of the # # Ionic SDK. # # # -# (c) 2017 Ionic Security Inc. # +# (c) 2017-2020 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 # diff --git a/example.py b/example.py index 44eafaf..ed33c9b 100644 --- a/example.py +++ b/example.py @@ -5,17 +5,17 @@ # using built-in and 3rd-party libraries instead of the # # Ionic SDK. # # # -# This example uses Python 3.4.3 # +# This example uses Python 3.4.3 or higher. # # This example is best read with syntax highlighting on. # # # -# (c) 2017 Ionic Security Inc. # +# (c) 2017-2020 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 = # ########################################################### +import os from keys import create_keys, fetch_keys from persistors import ProfilePersistorPlaintext @@ -29,8 +29,12 @@ if __name__ == "__main__": - persistor = ProfilePersistorPlaintext('profiles.pt') + persistor_path = os.path.expanduser("~/.ionicsecurity/profiles.pt") + persistor = ProfilePersistorPlaintext(persistor_path) ionic_sep = persistor.get_active_profile() + print("") + print("Current Device ID: " + getattr(ionic_sep, "deviceId")) + print("") # 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 @@ -41,6 +45,7 @@ } created_keys = create_keys(ionic_sep, dictKeyAttrs) print('Created keys: {}'.format(created_keys)) + print("") # 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. diff --git a/example_enroll.py b/example_enroll.py index f6dd951..cc6cb88 100644 --- a/example_enroll.py +++ b/example_enroll.py @@ -5,18 +5,18 @@ # using built-in and 3rd-party libraries instead of the # # Ionic SDK. # # # -# This example uses Python 3.4.3 # +# This example uses Python 3.4.3 or higher. # # This example is best read with syntax highlighting on. # # # -# (c) 2017 Ionic Security Inc. # +# (c) 2017-2020 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 +import os from registration import create_device from registration import get_ionic_token @@ -42,8 +42,10 @@ stoken = "" uidauth = "" -api_url = "https://dev-api.ionic.com/" -enrollment_server_url = "https://dev-enrollment.ionic.com/" +# These URLs are valid if you obtained your tenant using Start for Free, https://ionic.com/start-for-free/. +# Modify the keyspace to the keyspace of your tenant. +api_url = "https://api.ionic.com/" +enrollment_server_url = "https://enrollment.ionic.com/" keyspace = "ABcd" @@ -68,6 +70,7 @@ # 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") + persistor_path = os.path.expanduser("~/.ionicsecurity/profiles.pt") + persistor.set_file_path(persister_path) print(persistor) persistor.save_to_json() diff --git a/example_external_ids.py b/example_external_ids.py index 366c9b3..9a458ef 100644 --- a/example_external_ids.py +++ b/example_external_ids.py @@ -5,15 +5,14 @@ # using built-in and 3rd-party libraries instead of the # # Ionic SDK. # # # -# This example uses Python 3.4.3 # +# This example uses Python 3.4.3 or higher. # # This example is best read with syntax highlighting on. # # # -# (c) 2017 Ionic Security Inc. # +# (c) 2017-2020 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 diff --git a/keys/__init__.py b/keys/__init__.py index 3b1f781..8fa449c 100644 --- a/keys/__init__.py +++ b/keys/__init__.py @@ -5,7 +5,7 @@ # using builtin and 3rd-party libraries instead of the # # Ionic SDK. # # # -# (c) 2017 Ionic Security Inc. # +# (c) 2017-2020 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 # diff --git a/keys/key_create.py b/keys/key_create.py index e3bf1ce..d36355d 100644 --- a/keys/key_create.py +++ b/keys/key_create.py @@ -5,15 +5,14 @@ # using built-in and 3rd-party libraries instead of the # # Ionic SDK. # # # -# This example uses Python 3.4.3 # +# This example uses Python 3.4.3 or higher. # # This example is best read with syntax highlighting on. # # # -# (c) 2017 Ionic Security Inc. # +# (c) 2017-2020 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 = daniel/rmspeers, QA = jmassey # ########################################################### import base64 @@ -303,12 +302,15 @@ def create_key_transaction(ionic_sep, dictKeyAttrs, dictMetadata, send_full_hfp= ### Handling the Key Create Response ### ######################################## # Assume the response from Ionic is a successful 200, and we have created keys with the provided attributes. - assert (key_create_response.status_code == 200) or (key_create_response.status_code == 401) + status_code = key_create_response.status_code + assert (status_code == 200) or (status_code == 201), "\nKey Create response status code: %d\n" % status_code return key_create_response, cid, b64encoded_signed_attributes_iv_cipher_text_aad_as_string def create_keys(ionic_sep, dictKeyAttrs = {}, dictMetadata = {}): + # See https://dev.ionic.com/api/device/create-key for more information on key create. + key_create_response, cid, b64encoded_signed_attributes_iv_cipher_text_aad_as_string = create_key_transaction(ionic_sep, dictKeyAttrs, dictMetadata) decrypted_envelope, response_cid = utilities.decrypt_envelope(ionic_sep, key_create_response, cid) diff --git a/keys/key_fetch.py b/keys/key_fetch.py index 5aacd56..04972b1 100644 --- a/keys/key_fetch.py +++ b/keys/key_fetch.py @@ -5,15 +5,14 @@ # using built-in and 3rd-party libraries instead of the # # Ionic SDK. # # # -# This example uses Python 3.4.3 # +# This example uses Python 3.4.3 or higher. # # This example is best read with syntax highlighting on. # # # -# (c) 2017 Ionic Security Inc. # +# (c) 2017-2020 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 = daniel, QA = jmassey # ########################################################### import base64 @@ -131,57 +130,19 @@ def fetch_key_request(ionic_sep, protection_keys, external_id=None, send_full_hf headers={'Content-Type': 'application/json'}) # Assume the response from Ionic is a successful 200 and that we have received keys for the provided key tags. - assert (key_fetch_response.status_code == 200) or (key_fetch_response.status_code == 401) + status_code = key_fetch_response.status_code + assert (status_code == 200) or (status_code == 201), "\nKey Fetch response status code: %d\n" % status_code return key_fetch_response, cid -def decrypt_envelope(ionic_sep, key_fetch_response, cid): - ####################################### - ### Handling the Key Fetch Response ### - ####################################### - - key_fetch_response_body = key_fetch_response.json() - - # As a precaution, ensure that the client's CID is the same as the response's CID. - response_cid = key_fetch_response_body['cid'] - assert cid == response_cid - - # Base 64 decode the envelope's value. - decoded_key_fetch_response_envelope_as_bytes = base64.b64decode(key_fetch_response_body['envelope']) - - # Prepare to decrypt the `envelope` contents. - - # Obtain the initialization vector which is the first 16 bytes. - initialization_vector_from_response_envelope = decoded_key_fetch_response_envelope_as_bytes[:16] - - # Obtain the data to decrypt which is the bytes between the initializaiton vector and the tag. - cipher_text_from_response_envelope = decoded_key_fetch_response_envelope_as_bytes[16:-16] - - # Obtain the tag which is the last 16 bytes. - gcm_tag_from_response_envelope = decoded_key_fetch_response_envelope_as_bytes[-16:] - - # Construct a cipher to decrypt the data. - cipher = Cipher(algorithms.AES(ionic_sep.aesCdIdcKey), - modes.GCM(initialization_vector_from_response_envelope, - gcm_tag_from_response_envelope), - backend=default_backend() - ).decryptor() - - # Set the cipher's `aad` as the value of the `cid`. - cipher.authenticate_additional_data(response_cid.encode(encoding='utf-8')) - - # Decrypt the ciphertext. - decrypted_key_response_bytes = cipher.update(cipher_text_from_response_envelope) + cipher.finalize() - decrypted_envelope = json.loads(decrypted_key_response_bytes.decode(encoding='utf-8')) - - return decrypted_envelope - - def fetch_keys(ionic_sep, protection_keys, external_ids=None): ########################################## ### Constructing the Key Fetch Request ### ########################################## + + # See https://dev.ionic.com/api/device/get-key for more information on key fetch. + example_key_fetch_body = """ { "cid": "CID|MfyG..A.ec095b70-c1d0-4ac0-9d0f-2cafa82b8a1f|1487622171374|1487622171374|5bFnTQ==", @@ -216,7 +177,7 @@ def fetch_keys(ionic_sep, protection_keys, external_ids=None): "the full HFP included.") key_fetch_response, cid = fetch_key_request(ionic_sep, protection_keys, send_full_hfp=True) - decrypted_envelope = decrypt_envelope(ionic_sep, key_fetch_response, cid) + decrypted_envelope, _ = utilities.decrypt_envelope(ionic_sep, key_fetch_response, cid) # Pull out any query results as well to return: query_results = decrypted_envelope['data'].get('query-results') diff --git a/keys/utilities.py b/keys/utilities.py index 9a7acf6..7ca93d0 100644 --- a/keys/utilities.py +++ b/keys/utilities.py @@ -5,10 +5,10 @@ # using built-in and 3rd-party libraries instead of the # # Ionic SDK. # # # -# This example uses Python 3.4.3 # +# This example uses Python 3.4.3 or higher. # # This example is best read with syntax highlighting on. # # # -# (c) 2017 Ionic Security Inc. # +# (c) 2017-2020 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 # @@ -41,15 +41,23 @@ def make_cid(device_id): def decrypt_envelope(ionic_sep, server_response, cid): - response_body = server_response.json() + ####################################### + ### Handling the Key Fetch Response ### + ####################################### + + # See https://dev.ionic.com/api/device/get-key for more information on key fetch. + + key_fetch_response_body = server_response.json() # As a precaution, ensure that the client's CID is the same as the response's CID. - response_cid = response_body['cid'] + response_cid = key_fetch_response_body['cid'] if cid != response_cid: raise ValueError("The CID in the response did not match the one from the request.") # Base 64 decode the envelope's value. - decoded_response_envelope_as_bytes = base64.b64decode(response_body['envelope']) + decoded_response_envelope_as_bytes = base64.b64decode(key_fetch_response_body['envelope']) + # Prepare to decrypt the `envelope` contents. + # Prepare to decrypt the `envelope` contents. # Obtain the initialization vector which is the first 16 bytes. @@ -64,15 +72,15 @@ def decrypt_envelope(ionic_sep, server_response, cid): # Construct a cipher to decrypt the data. cipher = Cipher(algorithms.AES(ionic_sep.aesCdIdcKey), modes.GCM(initialization_vector_from_response_envelope, - gcm_tag_from_response_envelope), + gcm_tag_from_response_envelope), backend=default_backend() ).decryptor() # Set the cipher's `aad` as the value of the `cid` cipher.authenticate_additional_data(response_cid.encode(encoding='utf-8')) - decrypted_key_response_bytes = cipher.update(cipher_text_from_response_envelope) + cipher.finalize() # Decrypt the ciphertext. + decrypted_key_response_bytes = cipher.update(cipher_text_from_response_envelope) + cipher.finalize() decrypted_envelope = json.loads(decrypted_key_response_bytes.decode(encoding='utf-8')) return decrypted_envelope, response_cid diff --git a/persistors/__init__.py b/persistors/__init__.py index d72ef29..6ba0e51 100644 --- a/persistors/__init__.py +++ b/persistors/__init__.py @@ -5,7 +5,7 @@ # using builtin and 3rd-party libraries instead of the # # Ionic SDK. # # # -# (c) 2017 Ionic Security Inc. # +# (c) 2017-2020 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 # diff --git a/persistors/profile.py b/persistors/profile.py index 71d7838..ca1579b 100644 --- a/persistors/profile.py +++ b/persistors/profile.py @@ -5,15 +5,14 @@ # using built-in and 3rd-party libraries instead of the # # Ionic SDK. # # # -# This example uses Python 3.4.3 # +# This example uses Python 3.4.3 or higher. # # This example is best read with syntax highlighting on. # # # -# (c) 2017 Ionic Security Inc. # +# (c) 2017-2020 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 = # ########################################################### import binascii diff --git a/persistors/profile_persistor_plaintext.py b/persistors/profile_persistor_plaintext.py index e1da22f..faf1d44 100644 --- a/persistors/profile_persistor_plaintext.py +++ b/persistors/profile_persistor_plaintext.py @@ -5,15 +5,14 @@ # using built-in and 3rd-party libraries instead of the # # Ionic SDK. # # # -# This example uses Python 3.4.3 # +# This example uses Python 3.4.3 or higher. # # This example is best read with syntax highlighting on. # # # -# (c) 2017 Ionic Security Inc. # +# (c) 2017-2020 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 json diff --git a/registration/__init__.py b/registration/__init__.py index ce62c4d..21aa018 100644 --- a/registration/__init__.py +++ b/registration/__init__.py @@ -5,7 +5,7 @@ # using builtin and 3rd-party libraries instead of the # # Ionic SDK. # # # -# (c) 2017 Ionic Security Inc. # +# (c) 2017-2020 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 # diff --git a/registration/get_ionic_token.py b/registration/get_ionic_token.py index 68899fe..8fcc00f 100644 --- a/registration/get_ionic_token.py +++ b/registration/get_ionic_token.py @@ -7,15 +7,14 @@ # using builtin and 3rd-party libraries instead of the # # Ionic SDK. # # # -# This example uses Python 3.4.3 # +# This example uses Python 3.4.3 or higher. # # This example is best read with syntax highlighting on. # # # -# (c) 2017 Ionic Security Inc. # +# (c) 2017-2020 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 = jmassey, QA = rmspeers # ############################################################ import requests @@ -44,6 +43,9 @@ def get_authn(enrollment_url): def get_assertion(user, password, idp_url, saml_body): + # See https://dev.ionic.com/platform/enrollment/saml for more information on + # SAML authentication. + data = {"user": user, "password": password, "SAMLRequest": saml_body} login_response = requests.post(idp_url, data) saml_assertion = login_response.headers.get("X-Saml-Response", None) diff --git a/registration/register.py b/registration/register.py index 31a7ae9..f100bf2 100644 --- a/registration/register.py +++ b/registration/register.py @@ -5,15 +5,14 @@ # using builtin and 3rd-party libraries instead of the # # Ionic SDK. # # # -# This example uses Python 3.4.3 # +# This example uses Python 3.4.3 or higher. # # This example is best read with syntax highlighting on. # # # -# (c) 2017 Ionic Security Inc. # +# (c) 2017-2020 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 = jmassey/rmspeers, QA = daniel # ############################################################ import binascii diff --git a/requirements.txt b/requirements.txt index b8c533c..c44d4bd 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,11 +1,11 @@ -appdirs==1.4.0 -cffi==1.9.1 -cryptography==1.7.2 -idna==2.2 -packaging==16.8 -pyasn1==0.2.2 -pycparser==2.17 -pyOpenSSL==16.2.0 -pyparsing==2.1.10 -requests==2.13.0 -six==1.10.0 \ No newline at end of file +appdirs==1.4.4 +cffi==1.14.0 +cryptography==2.9.2 +idna==2.10 +packaging==20.4 +pyasn1==0.4.8 +pycparser==2.20 +pyOpenSSL==19.1.0 +pyparsing==2.4.7 +requests==2.24.0 +six==1.15.0