psiphon-tunnel-core/ClientLibrary

Psiphon Client Library README

Mobile

If you are planning to embed Psiphon in a mobile application, please use the MobileLibrary.

Using the Library in your App

First step: Review the sample code, located under example. This code provides an example of how to correctly use the client library.

Second step: Review the comments for Start and Stop in PsiphonTunnel.go. They describe the client interface.

Building for Darwin (iOS, MacOS)

Note that you will need to have Xcode installed on a machine running MacOS.

Run the build:

Ensure that the command below is run from within the ClientLibrary directory

./build-darwin.sh all

This command can also be modified by:

• replacing all with ios or macos as the first parameter to build-darwin.sh (as in ./build-darwin.sh ios) to only build binaries for the operating system of choice

When that command completes, the compiled binaries will be located in the build directory. The structure will be:

build
└── darwin
    └── ios
    │   └── PsiphonTunnel-ios-arm.h
    │   └── PsiphonTunnel-ios-arm.dylib
    │   └── PsiphonTunnel-ios-arm64.h
    │   └── PsiphonTunnel-ios-arm64.dylib
    └── macos
        └── PsiphonTunnel-macos-386.dylib
        └── PsiphonTunnel-macos-386.dylib
        └── PsiphonTunnel-macos-amd64.dylib
        └── PsiphonTunnel-macos-amd64.dylib

Building with Docker (Android, Linux, Windows)

Note that you may need to use sudo docker below, depending on your OS.

Create the build image:

1. While in the ClientLibrary directory, run the command: docker build --no-cache=true -t psiclientlibrary-builder .

2. Once completed, verify that you see an image named psiclientlibrary-builder when running: docker images

Run the build:

Ensure that the command below is run from within the ClientLibrary directory

The --user "$(id -u):$(id -g)" flag must be omitted when building on macOS because manually specifying the UID/GID will cause the build to fail since Docker on macOS handles host to container UID/GID mapping automatically and will be unable to map the manually specified UID/GID to the current user.

cd .. && \
  docker run \
  --platform=linux/amd64 \
  --user "$(id -u):$(id -g)" \
  --rm \
  -v $PWD:/go/src/github.com/Psiphon-Labs/psiphon-tunnel-core \
  psiclientlibrary-builder \
  /bin/bash -c './make.bash all' \
; cd -

This command can also be modified by:

• replacing all with android, linux, or windows as the first parameter to make.bash (as in ./make.bash windows) to only build binaries for the operating system of choice

When that command completes, the compiled binaries will be located in the build directory (./build, and everything under it will likely be owned by root, so be sure to chown to an appropriate user) under the current directory. The structure will be:

build
├── android
│   └── PsiphonTunnel-android-arm7.h
│   └── PsiphonTunnel-android-arm7.so
│   └── PsiphonTunnel-android-arm64.h
│   └── PsiphonTunnel-android-arm64.so
├── linux
│   └── PsiphonTunnel-linux-386.h
│   └── PsiphonTunnel-linux-386.so
│   └── PsiphonTunnel-linux-amd64.h
│   └── PsiphonTunnel-linux-amd64.so
└── windows
    └── PsiphonTunnel-windows-386.h
    └── PsiphonTunnel-windows-386.dll
    └── PsiphonTunnel-windows-amd64.h
    └── PsiphonTunnel-windows-amd64.dll