1# Overview 2 3libsignal-client contains platform-agnostic APIs useful for Signal client apps, exposed as a Java, 4Swift, or TypeScript library. The underlying implementations are written in Rust: 5 6- libsignal-protocol: Implements the Signal protocol, including the [Double Ratchet algorithm][]. A 7 replacement for [libsignal-protocol-java][] and [libsignal-metadata-java][]. 8- signal-crypto: Cryptographic primitives such as AES-GCM-SIV. We use [RustCrypto][]'s where we can 9 but sometimes have differing needs. 10- device-transfer: Support logic for Signal's device-to-device transfer feature. 11- poksho: Utilities for implementing zero-knowledge proofs; stands for "proof-of-knowledge, stateful-hash-object". See [zkgroup][]. 12 13This repository is used by the Signal client apps ([Android][], [iOS][], and [Desktop][]). Use 14outside of Signal is unsupported. In particular, the products of this repository are the Java, 15Swift, and TypeScript libraries that wrap the underlying Rust implementations. Those underlying 16implementations are subject to change without notice, as are the JNI, C, and Node add-on "bridge" 17layers. 18 19[Double Ratchet algorithm]: https://signal.org/docs/ 20[libsignal-protocol-java]: https://github.com/signalapp/libsignal-protocol-java 21[libsignal-metadata-java]: https://github.com/signalapp/libsignal-metadata-java 22[RustCrypto]: https://github.com/RustCrypto 23[zkgroup]: https://github.com/signalapp/zkgroup 24[Android]: https://github.com/signalapp/Signal-Android 25[iOS]: https://github.com/signalapp/Signal-iOS 26[Desktop]: https://github.com/signalapp/Signal-Desktop 27 28 29# Building 30 31To build anything in this repository you must have [Rust](https://rust-lang.org) installed. 32The build currently uses a specific version of the Rust nightly compiler, which 33will be downloaded automatically by cargo. To build and test the basic protocol 34libraries: 35 36```shell 37$ cargo build 38... 39$ cargo test 40... 41``` 42 43## Java/Android 44 45To build for Android you must install several additional packages including a JDK, 46the Android NDK/SDK, and add the Android targets to the Rust compiler, using 47 48```rustup target add armv7-linux-androideabi aarch64-linux-android i686-linux-android x86_64-linux-android``` 49 50as well as the Cargo NDK tool using 51 52```cargo install --version=1.0.0 cargo-ndk``` 53 54To build the Java/Android ``jar`` and ``aar``, and run the tests: 55 56```shell 57$ cd java 58$ ./gradlew test 59$ ./gradlew build # if you need AAR outputs 60``` 61 62Alternately, a build system using Docker is available: 63 64```shell 65$ cd java 66$ make java_test 67``` 68 69When exposing new APIs to Java, you will need to run `rust/bridge/jni/bin/gen_java_decl.py` in 70addition to rebuilding. 71 72 73## Swift 74 75To learn about the Swift build process see [``swift/README.md``](swift/) 76 77 78## Node 79 80You'll need Node installed to build. If you have [nvm][], you can run `nvm use` to select an 81appropriate version automatically. 82 83We use [`yarn`](https://classic.yarnpkg.com/) as our package manager. The Rust library will automatically be built when you run `yarn install`. 84 85```shell 86$ nvm use 87$ yarn install 88$ yarn tsc 89$ yarn test 90``` 91 92When testing changes locally, you can use `yarn build` to do an incremental rebuild of the Rust library. 93 94When exposing new APIs to Node, you will need to run `rust/bridge/node/bin/gen_ts_decl.py` in 95addition to rebuilding. 96 97[nvm]: https://github.com/nvm-sh/nvm 98 99 100# Contributions 101 102Signal does accept external contributions to this project. However unless the change is 103simple and easily understood, for example fixing a bug or portability issue, adding a new 104test, or improving performance, first open an issue to discuss your intended change as not 105all changes can be accepted. 106 107Contributions that will not be used directly by one of Signal's official client apps may still be 108considered, but only if they do not pose an undue maintenance burden or conflict with the goals of 109the project. 110 111Signing a [CLA (Contributor License Agreement)](https://signal.org/cla/) is required for all contributions. 112 113# Legal things 114## Cryptography Notice 115 116This distribution includes cryptographic software. The country in which you currently reside may have restrictions on 117the import, possession, use, and/or re-export to another country, of encryption software. BEFORE using any encryption 118software, please check your country's laws, regulations and policies concerning the import, possession, or use, and 119re-export of encryption software, to see if this is permitted. See <http://www.wassenaar.org/> for more information. 120 121The U.S. Government Department of Commerce, Bureau of Industry and Security (BIS), has classified this software as 122Export Commodity Control Number (ECCN) 5D002.C.1, which includes information security software using or performing 123cryptographic functions with asymmetric algorithms. The form and manner of this distribution makes it eligible for 124export under the License Exception ENC Technology Software Unrestricted (TSU) exception (see the BIS Export 125Administration Regulations, Section 740.13) for both object code and source code. 126 127## License 128 129Copyright 2020-2021 Signal Messenger, LLC 130 131Licensed under the AGPLv3: https://www.gnu.org/licenses/agpl-3.0.html 132