From 192bc8aea9d032423ba0fbeebb2eecd81cc3569a Mon Sep 17 00:00:00 2001 From: Craig Colegrove <34786857+giarc3@users.noreply.github.com> Date: Thu, 2 Jul 2020 17:06:41 -0600 Subject: [PATCH] Documentation improvements (#169) --- README.md | 135 +----------------- android/README.md | 77 ++++++++++ android/build.gradle | 2 +- .../examples/Example_Application/README.md | 15 +- .../Example_Application/app/build.gradle | 2 +- .../examples/Example_Application/build.gradle | 19 ++- .../gradle/wrapper/gradle-wrapper.properties | 4 +- .../gradle/wrapper/gradle-wrapper.properties | 6 +- cpp/BUILDING.md | 20 --- cpp/README.md | 25 ++++ java/README.md | 47 ++++++ 11 files changed, 183 insertions(+), 169 deletions(-) create mode 100644 android/README.md delete mode 100644 cpp/BUILDING.md create mode 100644 cpp/README.md create mode 100644 java/README.md diff --git a/README.md b/README.md index 8da7e004..4a9d894c 100644 --- 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:@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 new file mode 100644 index 00000000..582a1259 --- /dev/null +++ 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:@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 index 3d2086d1..b4d49b87 100644 --- 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 index 29460e99..ea51111f 100644 --- 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 index ebd35606..5ffdf3af 100644 --- 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 index 9c9f9dbd..694c3415 100644 --- a/android/examples/Example_Application/build.gradle +++ b/android/examples/Example_Application/build.gradle @@ -4,7 +4,7 @@ buildscript { jcenter() } dependencies { - classpath 'com.android.tools.build:gradle:3.6.2' + classpath 'com.android.tools.build:gradle:4.0.0' } } @@ -12,12 +12,23 @@ 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 +} \ No newline at end of file diff --git a/android/examples/Example_Application/gradle/wrapper/gradle-wrapper.properties b/android/examples/Example_Application/gradle/wrapper/gradle-wrapper.properties index e2de9791..51b195d8 100644 --- 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 index 2fddb453..b376a756 100644 --- 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 deleted file mode 100644 index 9ebbd493..00000000 --- a/cpp/BUILDING.md +++ /dev/null @@ -1,20 +0,0 @@ -# C++ Binding instructions - -The building of the CPP library is currently not done by CI, so if you're wanting to produce C/C++ bindings and the associated -library you'll need to follow the following steps. - -## Prerequisites - -- C++ 17 or greater installed. Most modern gcc or clang compilers should do -- C++ Boost installed. Search up directions for your distribution if you're not sure. -- CMake >= 3.9. -- Make - -## Building - -- Run `cmake .` in this directory. -- Run `make`. - -This should produce a binary `cpp-tests` as well as all the header files in `generated/sdk`. - -The dynamic library will be in `../target/release`. diff --git a/cpp/README.md b/cpp/README.md new file mode 100644 index 00000000..bd528b08 --- /dev/null +++ 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`. diff --git a/java/README.md b/java/README.md new file mode 100644 index 00000000..6695a4d2 --- /dev/null +++ b/java/README.md @@ -0,0 +1,47 @@ +# IronOxide-Java + +[![javadoc.io](https://javadoc.io/badge2/com.ironcorelabs/ironoxide-java/javadoc.io.svg)](https://javadoc.io/doc/com.ironcorelabs/ironoxide-java) + +## Installation + +### Library + +Download the appropriate binary for your operating system on the [releases](https://github.com/IronCoreLabs/ironoxide-swig-bindings/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 of the SDK classes can be imported from the `com.ironcorelabs.sdk` package. + +## Documentation + +Further documentation is available on [our docs site](https://ironcorelabs.com/docs/java/). + +## 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.