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