From b8b99373c5f6f4c7cffff84df3786643726e398e Mon Sep 17 00:00:00 2001 From: Nik Graf Date: Sat, 17 Feb 2024 18:07:17 +0100 Subject: [PATCH] docs: restructure documentation --- CONTRIBUTING.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++ README.md | 95 ++++++------------------------------------------- 2 files changed, 101 insertions(+), 85 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3eb164..bd1005b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,6 +4,32 @@ Contributions are always welcome, no matter how large or small! We want this community to be friendly and respectful to each other. Please follow it in all your interactions with the project. Before contributing, please read the [code of conduct](./CODE_OF_CONDUCT.md). +## Rust Setup + +```bash +cd rust +cargo install cxxbridge-cmd # (if not installed already) +rustup target add x86_64-apple-ios aarch64-apple-ios aarch64-apple-ios-sim # (if on macOS and not installed already) +rustup target add i686-linux-android x86_64-linux-android aarch64-linux-android arm-linux-androideabi # (if not installed already) +./build-all.sh # (inside the rust directory) +``` + +To pass additional arguments to cargo you can set the `EXTRA_ARGS` env variable. +For example, to do a release build with p256 feature: + +```bash +EXTRA_ARGS="--features p256" ./build-all.sh +``` + +We use the cxx crate to generate the glue code to expose a C++ interface from rust. +The cxx crate itself includes a C++ build step in its own build script. +Unfortunately cross-compilation for Android requires special care to use the NDK toolchain and it is currently not possible to set up target specific environment variables in a cargo config. +Therefore the rust project needs to be built with a separate build script `build-all.sh` (or `build-all.bat` on Windows). + +Since the C++ code generated by cxx further needs to be included by our XCode or Gradle+CMake build we use the `rust/gen-cxx.sh` script to invoke the `cxxbridge` command to generate the C++ source. +This requires the `cxxbridge-cmd` cargo package to be installed (`cargo install cxxbridge-cmd`). +Note that the `gen-cxx` script will be run at the end of `build-all` so you don't need to run it manually. + ## Development workflow To get started with the project, run `yarn` in the root directory to install the required dependencies for each package: @@ -64,6 +90,63 @@ To edit the Objective-C or Swift files, open `example/ios/OpaqueExample.xcworksp To edit the Java or Kotlin files, open `example/android` in Android studio and find the source files at `react-native-opaque` under `Android`. +## File Structure + +Directory overview: + +``` +/ + cpp/ + opaque-rust.cpp # generated from cxxbridge + opaque-rust.h + react-native-opaque.cpp # JSI bindings for the opaque_rust C++ interface + react-native-opaque.h + + rust/ + src/lib.rs # Rust source + build-android.{sh,bat} # Build library for given android target + build-all.{sh,bat} # Build all targets (only android on windows) + gen-cxx.{sh,bat} # Generate cxx source + + android/ + CMakeLists.txt # the build config where we set up the C++ source and link with the Rust lib + cpp-adapter.cpp # defines the JNI "initialize" function which installs opaque JSI functions + + react-native-opaque.podspec # build config for iOS to include the C++ and link with Rust lib +``` + +### iOS Build + +The podspec uses the `pod_target_xcconfig` setting to set up appropriate `LIBRARY_SEARCH_PATHS` and `LIBTOOLFLAGS` to link with the rust library and includes the `ios/` and `cpp/` source in the build. + +After the rust library is built you can run + +```bash +yarn example ios +``` + +as usual in the project root to build and run the iOS example app. + +### Android Build + +The `CMakeLists.txt` includes the `cpp/` source and links with the appropriate rust library target depending on the target arch. + +After the rust library is built you can run + +```bash +# list our emulators e.g. emulator -list-avds +# start the emulator e.g. emulator @Pixel_3a_API_33_arm64-v8a +yarn example android +``` + +as usual in the project root to build and run the Android example app. + +### Module initialization + +On both iOS and Android we define a react native module with a single `install` function (`ios/Opaque.mm` and `android/src/main/java/com/opaque/OpaqueModule.java`). +This install function is called when the module is imported on the JavaScript side which then calls the `installOpaque` function (in `cpp/react-native-opaque.cpp`) to register the opaque JSI functions. +On Android we need the additional `cpp-adapter.cpp` which defines a JNI function `initialize` which can be called from the Java side to indirectly call the `installOpaque` function on the native C++ side. + ### Commit message convention We follow the [conventional commits specification](https://www.conventionalcommits.org/en) for our commit messages: @@ -95,6 +178,14 @@ To publish new versions, run the following: yarn release ``` +### P256 Release + +Follow these steps: + +1. Sync the fork at [https://github.com/serenity-kit/react-native-opaque-p256](https://github.com/serenity-kit/react-native-opaque-p256) +2. Run the built script with `EXTRA_ARGS="--features p256" ./build-all.sh` +3. Run `yarn publish` to publish the new version to npm. + ### Scripts The `package.json` file contains various scripts for common tasks: diff --git a/README.md b/README.md index dbab27c..6559c14 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,10 @@ npm install react-native-opaque ```js import * as opaque from 'react-native-opaque'; -const { clientRegistration, registrationRequest } = - opaque.clientRegistrationStart('hunter2'); +const password = 'sup-krah.42-UOI'; // user password + +const { clientRegistrationState, registrationRequest } = + opaque.client.startRegistration({ password }); // ... ``` @@ -25,9 +27,11 @@ Since on web the package uses Web Assembly under the hood, it needs to be loaded ```ts import * as opaque from 'react-native-opaque'; +const password = 'sup-krah.42-UOI'; // user password + opaque.ready.then(() => { - const { clientRegistration, registrationRequest } = - opaque.clientRegistrationStart('hunter2'); + const { clientRegistrationState, registrationRequest } = + opaque.client.startRegistration({ password }); // ... }); ``` @@ -66,88 +70,9 @@ export default function LoadingApp() { Note: The `ready` Promise resolves right away on the native side. -## Build Setup - -Directory overview: - -``` -/ - cpp/ - opaque-rust.cpp # generated from cxxbridge - opaque-rust.h - react-native-opaque.cpp # JSI bindings for the opaque_rust C++ interface - react-native-opaque.h - - rust/ - src/lib.rs # Rust source - build-android.{sh,bat} # Build library for given android target - build-all.{sh,bat} # Build all targets (only android on windows) - gen-cxx.{sh,bat} # Generate cxx source - - android/ - CMakeLists.txt # the build config where we set up the C++ source and link with the Rust lib - cpp-adapter.cpp # defines the JNI "initialize" function which installs opaque JSI functions - - react-native-opaque.podspec # build config for iOS to include the C++ and link with Rust lib -``` - -### Rust Build - -```bash -cd rust -cargo install cxxbridge-cmd # (if not installed already) -rustup target add x86_64-apple-ios aarch64-apple-ios aarch64-apple-ios-sim # (if on macOS and not installed already) -rustup target add i686-linux-android x86_64-linux-android aarch64-linux-android arm-linux-androideabi # (if not installed already) -./build-all.sh # (inside the rust directory) -``` - -To pass additional arguments to cargo you can set the `EXTRA_ARGS` env variable. -For example, to do a release build with p256 feature: - -```bash -EXTRA_ARGS="--feature p256" ./build-all.sh -``` - -We use the cxx crate to generate the glue code to expose a C++ interface from rust. -The cxx crate itself includes a C++ build step in its own build script. -Unfortunately cross-compilation for Android requires special care to use the NDK toolchain and it is currently not possible to set up target specific environment variables in a cargo config. -Therefore the rust project needs to be built with a separate build script `build-all.sh` (or `build-all.bat` on Windows). - -Since the C++ code generated by cxx further needs to be included by our XCode or Gradle+CMake build we use the `rust/gen-cxx.sh` script to invoke the `cxxbridge` command to generate the C++ source. -This requires the `cxxbridge-cmd` cargo package to be installed (`cargo install cxxbridge-cmd`). -Note that the `gen-cxx` script will be run at the end of `build-all` so you don't need to run it manually. - -### iOS Build - -The podspec uses the `pod_target_xcconfig` setting to set up appropriate `LIBRARY_SEARCH_PATHS` and `LIBTOOLFLAGS` to link with the rust library and includes the `ios/` and `cpp/` source in the build. - -After the rust library is built you can run - -```bash -yarn example ios -``` - -as usual in the project root to build and run the iOS example app. - -### Android Build - -The `CMakeLists.txt` includes the `cpp/` source and links with the appropriate rust library target depending on the target arch. - -After the rust library is built you can run - -```bash -# list our emulators e.g. emulator -list-avds -# start the emulator e.g. emulator @Pixel_3a_API_33_arm64-v8a -yarn example android -``` - -as usual in the project root to build and run the Android example app. - -### Module initialization +## Documentation -On both iOS and Android we define a react native module with a single `install` function (`ios/Opaque.mm` and `android/src/main/java/com/opaque/OpaqueModule.java`). -This install function is called when the module is imported on the JavaScript side which then calls the `installOpaque` function (in `cpp/react-native-opaque.cpp`) to register the opaque JSI functions. -On Android we need the additional `cpp-adapter.cpp` which defines a JNI function `initialize` which can be called from the Java side to indirectly call the `installOpaque` function on the native C++ side. +In depth documentation can be found at [https://opaque-documentation.netlify.app/](https://opaque-documentation.netlify.app/). ## Contributing