Documentation improvements (#169)

IronCoreLabs · Jul 2, 2020 · 192bc8a · 192bc8a
1 parent 180c884
commit 192bc8a
Show file tree

Hide file tree

Showing 11 changed files with 183 additions and 169 deletions.
diff --git a/README.md b/README.md
@@ -1,139 +1,8 @@
-# IronCore Labs IronOxide Bindings
+# IronOxide Swig Bindings
 
-[![javadoc.io](https://javadoc.io/badge2/com.ironcorelabs/ironoxide-java/javadoc.io.svg)](https://javadoc.io/doc/com.ironcorelabs/ironoxide-java)
-
-This library is a thin Rust shim that wraps the [Rust SDK](https://github.com/IronCoreLabs/ironoxide) and uses the [Rust Swig](https://github.com/Dushistov/rust_swig) toolset to generate bindings. It currently contains SDKs for Java and Android.
-
-# IronOxide-Java
-
-## Installation
-
-### Library
-
-Download the appropriate binary for your operating system on the [releases](https://github.com/IronCoreLabs/ironoxide-java/releases) page:
-
-- `.so` for (default or Debian-based) Linux
-- `.dylib` for OSX
-
-(Optional) Verify the PGP signature by running `gpg --verify ${file}.asc`. Our fingerprint is `83F9 49C6 E7E2 F0A2 9564 2DEE 62F5 7B1B 8792 8CAC`.
-
-> If you encounter issues related to linked libraries, you may be able to get a working library built for your system by [building from source](#build-from-source).
-
-This binary should be placed in your Java library path,
-either by adding it to your `LD_LIBRARY_PATH` or the `-Djava.library.path` JVM option,
-and can then be loaded by calling:
-
-```java
-java.lang.System.loadLibrary("ironoxide_java")
-```
-
-### Java SDK
-
-The SDK is [published to Maven](https://search.maven.org/artifact/com.ironcorelabs/ironoxide-java).
-
-## Usage
-
-All the SDK classes can be imported from the `com.ironcorelabs.sdk` namespace.
-
-## Documentation
-
-Further documentation is available on [our docs site](https://docs.ironcorelabs.com/ironoxide-java-sdk/).
-
-## Build from Source
-
-### Prerequisites
-
-- [Rust toolchain](https://www.rust-lang.org/tools/install) installed
-- `JAVA_HOME` environment variable set
-- `clang` installed
-
-### Building
-
-From the root of this repository run `cargo build -p ironoxide-java`. The resulting `target/debug/build/ironoxide-java-*/out/java` directory will have the JNI binding code for the Java side and `target/debug` will have the dynamic library file you need to pull into your Java code. It will be named `libironoxide_java.so` or `libironoxide_java.dylib` depending on your environment. This library will only work on the architecture from which it was built.
-
-# IronOxide-Android
-
-## Using IronOxide-Android
-
-In order to make calls to the IronCore service, you must add a dependency for ironoxide-android, load the library, and provide authentication.
-
-### Adding a dependency
-
-IronOxide-Android is published to a custom maven repository. To pull from this repository, add the following to your project's "build.gradle":
-
-```java
-allprojects {
-    repositories {
-        maven {
-            url "https://oss.sonatype.org/content/repositories/snapshots"
-        }
-    }
-}
-```
-
-Then add the following to your module's "build.gradle":
-
-```java
-dependencies {
-    implementation 'com.ironcorelabs:ironoxide-android:<VERSION>@aar'
-}
-```
-
-### Loading the library
-
-To load the `ironoxide-android` library in Java, use the following:
-
-```java
-java.lang.System.loadLibrary("ironoxide_android");
-```
-
-### Authenticating
-
-To make calls, you must create a project and segment in the IronCore Admin Console. Once created, you can use a tool such as [ironoxide-cli](https://github.com/IronCoreLabs/ironoxide-cli) to create users and devices. You can then read in a device with the `DeviceContext.fromJsonString()` function and use it to initialize an IronOxide instance. An example of this is available in the [Example Application](/android/examples/Example_Application/) in "MainActivity.java".
-
-## Build from Source
-
-### Prerequisites
-
-- Install [Rust toolchain](https://www.rust-lang.org/tools/install).
-- Install [cross](https://github.com/rust-embedded/cross).
-- Install Android SDK 29. You can get the command line SDK [here](https://developer.android.com/studio) (scroll down to "Command line tools only").
-  - Note: **The extracted `tools` folder must follow a specific folder hierarchy. We recommend `AndroidCLI/cmdline-tools/tools`**.
-- Install Android 29 build and platform tools. This can be done with `sdkmanager` (found in `tools/bin`):
-
-  ```bash
-  ./sdkmanager "build-tools;29.0.3" "platform-tools" "platforms;android-29"
-  ```
-
-- Create the file `$HOME/.gradle/gradle.properties` and add the line `sdk.dir=PATH_TO_ANDROID_CLI_FOLDER`.
-
-### Building
-
-From the repository root, run `android/build.sh`. This will put the compiled library and generated Java files into `android/ironoxide-android/src/main`.
-
-## Testing
-
-### Prerequisites
-
-- Successfully run `build.sh` by following the steps in [Build from Source](#build-from-source-1).
-  - This will create the java files and the `.so` files required for the `x86`, `x86_64`, and `arm64-v8a` architectures. If testing on a different architecture, you can find the Rust target to compile to [here](https://forge.rust-lang.org/release/platform-support.html).
-- An Android emulator running, or a compatible Android phone connected.
-  - To start an emulator using the command line tools, follow these steps from the folder `AndroidCLI/cmdline-tools/tools/bin`:
-    1. `./sdkmanager "emulator" "system-images;android-29;google_apis;x86_64"`
-    2. `./avdmanager create avd -n pixel_3 -k "system-images;android-29;google_apis;x86_64" -d pixel_3`
-    3. `../../../emulator/emulator -avd pixel_3 -no-window -gpu swiftshader_indirect -no-snapshot -noaudio -no-boot-anim`
-  - The emulator may take some time to boot, but the output will include `emulator: INFO: boot completed` when it has completed. You will need to use a different terminal to run the tests.
-
-### Running the Connected Android Tests
-
-Run the tests from the `android` folder with:
-
-```bash
-./gradlew connectedAndroidTest
-```
+This library is a thin Rust shim that wraps the [IronOxide Rust SDK](https://github.com/IronCoreLabs/ironoxide) and uses the [Rust Swig](https://github.com/Dushistov/rust_swig) toolset to generate bindings. It currently contains SDKs for [C++](cpp/README.md), [Java](java/README.md), and [Android](android/README.md).
 
 # License
 
 Copyright (c) 2020 IronCore Labs, Inc.
 All rights reserved.
-
diff --git a/android/README.md b/android/README.md
@@ -0,0 +1,77 @@
+# IronOxide-Android
+
+[![javadoc.io](https://javadoc.io/badge2/com.ironcorelabs/ironoxide-java/javadoc.io.svg)](https://javadoc.io/doc/com.ironcorelabs/ironoxide-java)
+
+## Using IronOxide-Android
+
+In order to make calls to the IronCore service, you must add a dependency for ironoxide-android, load the library, and provide authentication.
+
+### Adding a dependency
+
+Add the following to your module's "build.gradle":
+
+```java
+dependencies {
+    implementation 'com.ironcorelabs:ironoxide-android:<VERSION>@aar'
+}
+```
+
+### Loading the library
+
+To load the `ironoxide-android` library in Java, use the following:
+
+```java
+java.lang.System.loadLibrary("ironoxide_android");
+```
+
+### Authenticating
+
+To make calls, you must create a project and segment in the IronCore [Admin Console](https://admin.ironcorelabs.com). These are necessary to create an IronCore JWT that can be used to create users and generate devices.
+The JWT must use either the ES256 or RS256 algorithm and have a payload similar to IronOxide's [JwtClaims](https://docs.rs/ironoxide/0.23.0/ironoxide/user/struct.JwtClaims.html).
+
+Alternatively, once you have created a project and a segment, you can use a tool such as [ironoxide-cli](https://github.com/IronCoreLabs/ironoxide-cli) to create users and devices directly.
+You can then read in a device with the `DeviceContext.fromJsonString()` function and use it to initialize an `IronOxide` instance. An example of this is available in the
+[Example Application](/android/examples/Example_Application/) in "MainActivity.java".
+
+## Build from Source
+
+### Prerequisites
+
+- Install [Rust toolchain](https://www.rust-lang.org/tools/install).
+- Install [cross](https://github.com/rust-embedded/cross).
+- Install Android SDK 29. You can get the command line SDK [here](https://developer.android.com/studio) (scroll down to "Command line tools only").
+  - Note: **The extracted `tools` folder must follow a specific folder hierarchy. We recommend `AndroidCLI/cmdline-tools/tools`**.
+- Install Android 29 build and platform tools. This can be done with `sdkmanager` (found in `tools/bin`):
+
+  ```bash
+  ./sdkmanager "build-tools;29.0.3" "platform-tools" "platforms;android-29"
+  ```
+
+- Create the file `$HOME/.gradle/gradle.properties` and add the line `sdk.dir=PATH_TO_ANDROID_CLI_FOLDER`.
+
+### Building
+
+From the repository root, run `android/build.sh`.
+
+This will compile IronOxide-Android for `x86_64` Android phones. If building for a different architecture, you can find the Rust target to compile to
+[here](https://forge.rust-lang.org/release/platform-support.html) and modify the `cross build` command in `build.sh`. The compiled library and generated Java files will be put into `android/ironoxide-android/src/main`.
+
+## Testing
+
+### Prerequisites
+
+- Successfully run `build.sh` by following the steps in [Build from Source](#build-from-source-1).
+- An Android emulator running, or a compatible Android phone connected.
+  - To start an emulator using the command line tools, follow these steps from the folder `AndroidCLI/cmdline-tools/tools/bin`:
+    1. `./sdkmanager "emulator" "system-images;android-29;google_apis;x86_64"`
+    2. `./avdmanager create avd -n pixel_3 -k "system-images;android-29;google_apis;x86_64" -d pixel_3`
+    3. `../../../emulator/emulator -avd pixel_3 -no-window -gpu swiftshader_indirect -no-snapshot -noaudio -no-boot-anim`
+  - The emulator may take some time to boot, but the output will include `emulator: INFO: boot completed` when it has completed. You will need to use a different terminal to run the tests.
+
+### Running the Connected Android Tests
+
+Run the tests from the `android` folder with:
+
+```bash
+./gradlew connectedAndroidTest
+```
diff --git a/android/build.gradle b/android/build.gradle
@@ -5,7 +5,7 @@ buildscript {
         mavenCentral()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:3.5.0'
+        classpath 'com.android.tools.build:gradle:4.0.0'
         classpath "io.codearte.gradle.nexus:gradle-nexus-staging-plugin:0.21.2"
     }
 }

diff --git a/android/examples/Example_Application/README.md b/android/examples/Example_Application/README.md
@@ -8,16 +8,21 @@ This application provides a simple UI for encrypting/decrypting data with IronCo
 
 ### Prerequisites
 
-- Environment variable `ANDROID_SDK_ROOT` set to the Android Sdk install location
-- Android SDK 29. You can get the command line SDK [here](https://developer.android.com/studio) (scroll down to "Command line tools only") and use `sdkmanager` (found in tools/bin) to install additional prerequisites:
+- Install Android SDK 29. You can get the command line SDK [here](https://developer.android.com/studio) (scroll down to "Command line tools only").
+  - Note: **The extracted `tools` folder must follow a specific folder hierarchy. We recommend `AndroidCLI/cmdline-tools/tools`**.
+- Install Android 29 build and platform tools. This can be done with `sdkmanager` (found in `tools/bin`):
   ```bash
-    ./sdkmanager --sdk_root=PATH_TO_SDK_INSTALL_LOCATION --install "build-tools;29.0.3" "platform-tools" "platforms;android-29" "emulator"
+  ./sdkmanager "build-tools;29.0.3" "platform-tools" "platforms;android-29"
   ```
-- An Android Virtual Device (AVD)
+- Create/edit the file `$HOME/.gradle/gradle.properties` and add the line `sdk.dir=PATH_TO_ANDROID_CLI_FOLDER`.
+- An Android emulator running, or a compatible Android phone connected.
+  - To start an emulator using the command line tools, follow these steps from the folder `AndroidCLI/cmdline-tools/tools/bin`:
+    1. `./sdkmanager "emulator" "system-images;android-29;google_apis;x86_64"`
+    1. `./avdmanager create avd -n pixel_3 -k "system-images;android-29;google_apis;x86_64" -d pixel_3`
+    1. `../../../emulator/emulator -avd pixel_3 -no-snapshot -noaudio -no-boot-anim`
 
 ### Directions
 
-1. Start the AVD.
 1. From the Example_Application root, run `./gradlew installDebug`.
 1. From the emulator's app drawer, select the `ICL Demo` app.
 1. Fill out the `Name` and `Data` fields and press the `Encrypt` button. A new entry will be added for this data below.

diff --git a/android/examples/Example_Application/app/build.gradle b/android/examples/Example_Application/app/build.gradle
@@ -14,7 +14,7 @@ android {
 }
 
 dependencies {
-    implementation 'com.ironcorelabs:ironoxide-android:0.14.1@aar'
+    implementation 'com.ironcorelabs:ironoxide-android:0.13.1@aar'
     implementation 'androidx.appcompat:appcompat:1.1.0'
     implementation 'androidx.constraintlayout:constraintlayout:1.1.3'
     implementation 'androidx.recyclerview:recyclerview:1.1.0'

diff --git a/android/examples/Example_Application/build.gradle b/android/examples/Example_Application/build.gradle
@@ -4,20 +4,31 @@ buildscript {
         jcenter()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:3.6.2'
+        classpath 'com.android.tools.build:gradle:4.0.0'
     }
 }
 
 allprojects {
     repositories {
         google()
         jcenter()
-        maven {
-            url "https://oss.sonatype.org/content/repositories/snapshots"
-        }
     }
 }
 
 task clean(type: Delete) {
     delete rootProject.buildDir
 }
+
+// Ensure we know where the Android SDK is.
+try {
+    String sdkDir = findProperty("sdk.dir")
+    if (sdkDir == null) {
+        sdkDir = System.getenv("ANDROID_HOME")
+    }
+    if (!file(sdkDir).isDirectory()) throw new Exception()
+    // Couldn't find this documented anywhere; see https://android.googlesource.com/platform/tools/build/+/6d7fd0d2eff092abf1aaf44d03756b24570b390c/gradle/src/main/groovy/com/android/build/gradle/internal/Sdk.groovy#187
+    System.properties["android.home"] = property("sdk.dir")
+} catch (Exception e) {
+    // throw new GradleException("sdk.dir must point to the Android SDK. Set it in \$HOME/.gradle/gradle.properties")
+    throw e
+}
diff --git a/android/examples/Example_Application/gradle/wrapper/gradle-wrapper.properties b/android/examples/Example_Application/gradle/wrapper/gradle-wrapper.properties
@@ -1,6 +1,6 @@
-#Tue Apr 07 13:29:29 MDT 2020
+#Wed Jun 24 10:48:40 MDT 2020
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-5.6.4-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-6.5-all.zip
diff --git a/android/gradle/wrapper/gradle-wrapper.properties b/android/gradle/wrapper/gradle-wrapper.properties
@@ -1,6 +1,6 @@
-#Fri Mar 20 15:26:09 MDT 2020
+#Wed Jun 24 10:49:48 MDT 2020
 distributionBase=GRADLE_USER_HOME
-distributionUrl=https\://services.gradle.org/distributions/gradle-5.4.1-all.zip
 distributionPath=wrapper/dists
-zipStorePath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-6.5-all.zip
diff --git a/cpp/BUILDING.md b/cpp/BUILDING.md
diff --git a/cpp/README.md b/cpp/README.md
@@ -0,0 +1,25 @@
+# IronOxide-Cpp
+
+## Build from Source
+
+### Prerequisites
+
+- C++ 17 or greater installed. Most modern gcc or clang compilers should do.
+- CMake >= 3.9.
+- Make
+
+### Building
+
+From the `cpp` directory, run:
+
+```
+cmake .
+make
+```
+
+This will output all of the header files to `ironoxide-swig-bindings/cpp/generated/sdk` and the dynamic library `libironoxide` to `ironoxide-swig-bindings/target/release`.
+The file extension of the dynamic library will depend on your operating system (`.so` for Linux, `.dylib` for OSX, etc.).
+
+## Testing
+
+After running the steps in [Building](#building), the C++ tests can be run from the `cpp` directory with `./cpp-tests`.