react-native-opaque

React Native client for the OPAQUE Protocol

Installation

npm install react-native-opaque

Usage

import * as opaque from 'react-native-opaque';

const { clientRegistration, registrationRequest } =
  opaque.clientRegistrationStart('hunter2');
// ...

Usage with React Native Web

Since on web the package uses Web Assembly under the hood, it needs to be loaded asynchronously. To offer the same API the module is loaded internally, but in addition the API offers a ready Promise that will resolve once the module is loaded and ready to be used.

import * as opaque from 'react-native-opaque';

opaque.ready.then(() => {
  const { clientRegistration, registrationRequest } =
    opaque.clientRegistrationStart('hunter2');
  // ...
});

The most convenient way to use this is to have loading page that waits for the ready Promise to resolve before rendering the actual app.

For example:

export default function LoadingApp() {
  const [opaqueModuleStatus, setOpaqueModuleStatus] = React.useState<
    'loading' | 'failed' | 'loaded'
  >('loading');

  React.useEffect(() => {
    async function waitForOpaque() {
      try {
        await opaque.ready;
        setOpaqueModuleStatus('loaded');
      } catch (e) {
        console.warn(e);
        setOpaqueModuleStatus('failed');
      }
    }

    waitForOpaque();
  }, []);

  if (opaqueModuleStatus === 'loading') return null;
  if (opaqueModuleStatus === 'failed')
    return <Text>Failed to load resources. Please reload the app.</Text>;

  return <App />;
}

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

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:

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

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

# 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.

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

Made with create-react-native-library

Acknowledgement

This project was supported by the Netidee funding campaign.