libsignal

Home to the Signal Protocol as well as other cryptographic primitives which make Signal possible.

4,329

512

4,329

View on GitHub View on NPM

Top Related Projects

matrix-js-sdk

1,726

Matrix Client-Server SDK for JavaScript

element-web

11,694

A glossy Matrix collaboration client for the web.

status-mobile

3,941

a free (libre) open source, mobile OS for Ethereum

Quick Overview

libsignal is a cryptographic library used to implement the Signal Protocol, which provides end-to-end encryption for instant messaging, voice calls, and video calls. It is the core component of the Signal messaging app and is also used by other applications to implement secure communication features.

Pros

Strong security: Implements state-of-the-art cryptographic protocols for secure communication
Cross-platform support: Available for multiple programming languages and platforms
Open-source: Allows for community auditing and contributions
Well-documented: Provides comprehensive documentation for developers

Cons

Complex implementation: Requires a deep understanding of cryptography to use effectively
Limited features: Focuses solely on encryption, lacking other messaging-related functionalities
Potential regulatory challenges: Strong encryption may face legal obstacles in some jurisdictions

Code Examples

Generating a key pair:

IdentityKeyPair identityKeyPair = KeyHelper.generateIdentityKeyPair();

Creating a session:

SessionBuilder sessionBuilder = new SessionBuilder(sessionStore, remoteAddress);
sessionBuilder.process(preKeyBundle);

Encrypting a message:

SessionCipher sessionCipher = new SessionCipher(sessionStore, remoteAddress);
CiphertextMessage message = sessionCipher.encrypt("Hello, Signal!".getBytes());

Decrypting a message:

SessionCipher sessionCipher = new SessionCipher(sessionStore, remoteAddress);
byte[] plaintext = sessionCipher.decrypt(new SignalMessage(message.serialize()));

Getting Started

To use libsignal in your Java project:

Add the dependency to your build.gradle file:

dependencies {
    implementation 'org.whispersystems:signal-protocol-java:2.8.1'
}

Import the necessary classes:

import org.whispersystems.libsignal.*;
import org.whispersystems.libsignal.state.*;
import org.whispersystems.libsignal.protocol.*;

Initialize the required stores:

SignalProtocolStore protocolStore = new InMemorySignalProtocolStore();
SessionStore sessionStore = protocolStore.getSessionStore();
PreKeyStore preKeyStore = protocolStore.getPreKeyStore();
SignedPreKeyStore signedPreKeyStore = protocolStore.getSignedPreKeyStore();
IdentityKeyStore identityKeyStore = protocolStore.getIdentityKeyStore();

Now you can start using libsignal to implement secure communication in your application.

Competitor Comparisons

Signal-Android

26,335

A private messenger for Android.

Pros of Signal-Android

Full-featured Android application with a user interface
Implements end-to-end encryption for messaging and calls
Integrates with Android system features and notifications

Cons of Signal-Android

Larger codebase, potentially more complex to maintain
Specific to Android platform, not cross-platform
May require more frequent updates due to Android OS changes

Code Comparison

Signal-Android (Java):

public class SignalServiceMessageSender {
    public void sendMessage(SignalServiceAddress address, 
                            SignalServiceDataMessage message) {
        // Implementation for sending encrypted messages
    }
}

libsignal (C):

int signal_protocol_session_cipher_encrypt(
    signal_protocol_session_cipher *cipher,
    const uint8_t *plaintext, size_t plaintext_len,
    ciphertext_message **encrypted_message)
{
    // Implementation for encrypting messages
}

Key Differences

Signal-Android is a full Android app, while libsignal is a core cryptographic library
Signal-Android is written in Java, libsignal in C
libsignal provides low-level cryptographic operations, Signal-Android implements higher-level messaging features
Signal-Android includes UI components, libsignal is purely backend functionality

Signal-iOS

11,235

A private messenger for iOS.

Pros of Signal-iOS

Complete iOS application with user interface and full functionality
Integrates directly with iOS-specific features and APIs
Provides a reference implementation for Signal on iOS devices

Cons of Signal-iOS

Larger codebase, potentially more complex to maintain
Platform-specific, not suitable for cross-platform development
May require more frequent updates to keep up with iOS changes

Code Comparison

Signal-iOS (Swift):

class SignalApp: NSObject, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // iOS-specific initialization
        return true
    }
}

libsignal (C):

#include <signal_protocol.h>

int main() {
    signal_context *global_context;
    signal_protocol_store_context *store_context;
    // Core Signal Protocol operations
    return 0;
}

Key Differences

Signal-iOS is a full iOS app, while libsignal is a core cryptographic library
Signal-iOS uses Swift, tailored for iOS development; libsignal uses C for broader compatibility
libsignal focuses on the Signal Protocol implementation, while Signal-iOS includes UI and platform integration
Signal-iOS is specific to Apple's ecosystem, whereas libsignal can be used across various platforms and languages

matrix-js-sdk

1,726

Matrix Client-Server SDK for JavaScript

Pros of matrix-js-sdk

Broader scope: Supports a wide range of Matrix protocol features, including room management, user profiles, and device verification
More extensive documentation: Offers comprehensive guides and API references
Active community: Regular updates and contributions from a diverse developer base

Cons of matrix-js-sdk

Larger codebase: May be more complex to integrate and maintain
Potentially slower performance: Due to its broader feature set, it might have more overhead
Less focus on encryption: While it supports end-to-end encryption, it's not the primary focus like in libsignal

Code Comparison

libsignal (Rust):

let alice_address = ProtocolAddress::new("+14151111111".to_owned(), 1);
let bob_address = ProtocolAddress::new("+14151111112".to_owned(), 1);
let message = "Hello, World!".as_bytes();
let ciphertext = encrypt(&alice_store, &bob_address, message)?;

matrix-js-sdk (JavaScript):

const client = matrixcs.createClient(homeserverUrl);
await client.login("m.login.password", { user: "alice", password: "secret" });
const roomId = await client.createRoom({ preset: "private_chat" });
await client.sendMessage(roomId, { msgtype: "m.text", body: "Hello, World!" });

This comparison highlights the different focus areas of the two libraries. libsignal emphasizes secure messaging primitives, while matrix-js-sdk provides a higher-level API for interacting with the Matrix protocol, including room creation and message sending.

element-web

11,694

A glossy Matrix collaboration client for the web.

Pros of Element Web

Offers a full-featured web client for Matrix, providing a complete user interface
Supports a wide range of features including end-to-end encryption, VoIP calls, and file sharing
Highly customizable and can be self-hosted, giving users more control over their data

Cons of Element Web

Larger codebase and more complex architecture compared to libsignal
May have a steeper learning curve for developers new to the Matrix ecosystem
Performance can be impacted by the extensive feature set and web-based nature

Code Comparison

Element Web (React component):

export default class MatrixChat extends React.PureComponent {
    static displayName = 'MatrixChat'
    state = {
        view: Views.LOADING,
    };
    // ...
}

libsignal (Rust implementation):

pub struct SessionBuilder<'a> {
    identity_key_store: &'a dyn IdentityKeyStore,
    session_store: &'a dyn SessionStore,
    pre_key_store: &'a dyn PreKeyStore,
    signed_pre_key_store: &'a dyn SignedPreKeyStore,
}

While Element Web focuses on providing a complete client application, libsignal is a library for implementing the Signal protocol. Element Web uses React for its UI, while libsignal is primarily implemented in Rust for performance and safety.

status-mobile

3,941

a free (libre) open source, mobile OS for Ethereum

Pros of Status-mobile

Full-featured mobile app with integrated wallet and Web3 browser
Built with React Native, allowing for cross-platform development
Active community and frequent updates

Cons of Status-mobile

Larger codebase and more complex architecture
Potentially slower performance due to React Native framework
Broader scope may lead to more security vulnerabilities

Code Comparison

Status-mobile (React Native):

import React from 'react';
import { View, Text } from 'react-native';

const MessageBubble = ({ message }) => (
  <View style={styles.bubble}>
    <Text>{message.text}</Text>
  </View>
);

Libsignal (C++):

#include "signal_protocol.h"

int encrypt_message(signal_protocol_store_context *store_context,
                    const char *recipient_id, const char *message) {
  // Encryption logic here
}

Summary

Status-mobile is a comprehensive mobile app with integrated Web3 features, while Libsignal is a focused encryption library. Status-mobile offers a broader range of functionality but may have performance trade-offs. Libsignal provides a lower-level encryption implementation with potentially better performance and security, but requires more integration work for a full application.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Overview

libsignal contains platform-agnostic APIs used by the official Signal clients and servers, exposed as a Java, Swift, or TypeScript library. The underlying implementations are written in Rust:

libsignal-protocol: Implements the Signal protocol, including the Double Ratchet algorithm. A replacement for libsignal-protocol-java and libsignal-metadata-java.
signal-crypto: Cryptographic primitives such as AES-GCM. We use RustCrypto's where we can but sometimes have differing needs.
device-transfer: Support logic for Signal's device-to-device transfer feature.
attest: Functionality for remote attestation of SGX enclaves and server-side HSMs.
zkgroup: Functionality for zero-knowledge groups and related features available in Signal.
zkcredential: An abstraction for the sort of zero-knowledge credentials used by zkgroup, based on the paper "The Signal Private Group System" by Chase, Perrin, and Zaverucha.
poksho: Utilities for implementing zero-knowledge proofs (such as those used by zkgroup); stands for "proof-of-knowledge, stateful-hash-object".
account-keys: Functionality for consistently using PINs as passwords in Signal's Secure Value Recovery system, as well as other account-wide key operations.
usernames: Functionality for username generation, hashing, and proofs.
media: Utilities for manipulating media.

This repository is used by the Signal client apps (Android, iOS, and Desktop) as well as server-side. Use outside of Signal is unsupported. In particular, the products of this repository are the Java, Swift, and TypeScript libraries that wrap the underlying Rust implementations. All APIs and implementations are subject to change without notice, as are the JNI, C, and Node add-on "bridge" layers. However, backwards-incompatible changes to the Java, Swift, TypeScript, and non-bridge Rust APIs will be reflected in the version number on a best-effort basis, including increases to the minimum supported tools versions.

Building

Toolchain Installation

To build anything in this repository you must have Rust installed, as well as Clang, libclang, CMake, Make, protoc, and git.

Linux/Debian

On a Debian-like system, you can get these extra dependencies through apt:

$ apt-get install clang libclang-dev cmake make protobuf-compiler git

macOS

On macOS, we have a best-effort maintained script to set up the Rust toolchain you can run by:

$ bin/mac_setup.sh

Rust

First Build and Test

The build currently uses a specific version of the Rust nightly compiler, which will be downloaded automatically by cargo. To build and test the basic protocol libraries:

$ cargo build
...
$ cargo test
...

Additional Rust Tools

The basic tools above should get you set up for most libsignal Rust development.

Eventually, you may find that you need some additional Rust tools like cbindgen to modify the bridges to the client libraries or taplo for code formatting.

You should always install any Rust tools you need that may affect the build from cargo rather than from your system package manager (e.g. apt or brew). Package managers sometimes contain outdated versions of these tools that can break the build with incompatibility issues (especially cbindgen).

To install the main Rust extra dependencies matching the versions we use, you can run the following commands:

$ cargo +stable install cbindgen cargo-fuzz
$ cargo +stable install --version "$(cat ../acknowledgments/cargo-about-version)" --locked cargo-about
$ cargo +stable install --version "$(cat ../.taplo-cli-version)" --locked taplo-cli

Java/Android

To build for Android you must install several additional packages including a JDK, the Android NDK/SDK, and add the Android targets to the Rust compiler, using

rustup target add armv7-linux-androideabi aarch64-linux-android i686-linux-android x86_64-linux-android

To build the Java/Android jar and aar, and run the tests:

$ cd java
$ ./gradlew test
$ ./gradlew build # if you need AAR outputs

You can pass -P debugLevelLogs to Gradle to build without filtering out debug- and verbose-level logs from Rust.

Alternately, a build system using Docker is available:

$ cd java
$ make

When exposing new APIs to Java, you will need to run rust/bridge/jni/bin/gen_java_decl.py in addition to rebuilding. This requires installing the cbindgen Rust tool, as detailed above.

Maven Central

Signal publishes Java packages on Maven Central for its own use, under the names org.signal:libsignal-server, org.signal:libsignal-client, and org.signal:libsignal-android. libsignal-client and libsignal-server contain native libraries for Debian-flavored x86_64 Linux as well as Windows (x86_64) and macOS (x86_64 and arm64). libsignal-android contains native libraries for armeabi-v7a, arm64-v8a, x86, and x86_64 Android.

When building for Android you need both libsignal-android and libsignal-client, but the Windows and macOS libraries in libsignal-client won't automatically be excluded from your final app. You can explicitly exclude them using packagingOptions:

android {
  // ...
  packagingOptions {
    resources {
      excludes += setOf("libsignal_jni*.dylib", "signal_jni*.dll")
    }
  }
  // ...
}

You can additionally exclude libsignal_jni_testing.so if you do not plan to use any of the APIs intended for client testing.

Swift

To learn about the Swift build process see swift/README.md

Node

You'll need Node installed to build. If you have nvm, you can run nvm use to select an appropriate version automatically.

We use npm as our package manager, and node-gyp to control building the Rust library.

$ cd node
$ nvm use
$ npm install
$ npx node-gyp rebuild  # clean->configure->build
$ npm run tsc
$ npm run test

When testing changes locally, you can use npm run build to do an incremental rebuild of the Rust library. Alternately, npm run build-with-debug-level-logs will rebuild without filtering out debug- and verbose-level logs.

When exposing new APIs to Node, you will need to run rust/bridge/node/bin/gen_ts_decl.py in addition to rebuilding.

NPM

Signal publishes the NPM package @signalapp/libsignal-client for its own use, including native libraries for Windows, macOS, and Debian-flavored Linux. Both x64 and arm64 builds are included for all three platforms, but the arm64 builds for Windows and Linux are considered experimental, since there are no official builds of Signal for those architectures.

Contributions

Signal does accept external contributions to this project. However unless the change is simple and easily understood, for example fixing a bug or portability issue, adding a new test, or improving performance, first open an issue to discuss your intended change as not all changes can be accepted.

Contributions that will not be used directly by one of Signal's official client apps may still be considered, but only if they do not pose an undue maintenance burden or conflict with the goals of the project.

Signing a CLA (Contributor License Agreement) is required for all contributions.

Code Formatting and Acknowledgments

You can run the styler on the entire project by running:

just format-all

You can run more extensive tests as well as linters and clippy by running:

just check-pre-commit

When making a PR that adjusts dependencies, you'll need to regenerate our acknowledgments files. See acknowledgments/README.md.

Legal things

Cryptography Notice

This distribution includes cryptographic software. The country in which you currently reside may have restrictions on the import, possession, use, and/or re-export to another country, of encryption software. BEFORE using any encryption software, please check your country's laws, regulations and policies concerning the import, possession, or use, and re-export of encryption software, to see if this is permitted. See http://www.wassenaar.org/ for more information.

The U.S. Government Department of Commerce, Bureau of Industry and Security (BIS), has classified this software as Export Commodity Control Number (ECCN) 5D002.C.1, which includes information security software using or performing cryptographic functions with asymmetric algorithms. The form and manner of this distribution makes it eligible for export under the License Exception ENC Technology Software Unrestricted (TSU) exception (see the BIS Export Administration Regulations, Section 740.13) for both object code and source code.

License

Licensed under the GNU AGPLv3: https://www.gnu.org/licenses/agpl-3.0.html

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot