Descripción general

libsignal contiene APIs agnósticas de la plataforma utilizadas por los clientes y servidores oficiales de Signal, expuestas como una biblioteca Java, Swift o TypeScript. Las implementaciones subyacentes están escritas en Rust:

libsignal-protocol: Implementa el protocolo Signal, incluido el algoritmo Double Ratchet. Un reemplazo de libsignal-protocol-java y libsignal-metadata-java.
signal-crypto: Primitivas criptográficas como AES-GCM. Usamos las de RustCrypto cuando podemos, pero a veces tenemos necesidades diferentes.
device-transfer: Lógica de soporte para la función de transferencia de dispositivo a dispositivo de Signal.
attest: Funcionalidad para atestación remota de enclaves SGX y HSMs del lado del servidor.
zkgroup: Funcionalidad para grupos de conocimiento cero y características relacionadas disponibles en Signal.
zkcredential: Una abstracción para el tipo de credenciales de conocimiento cero utilizadas por zkgroup, basada en el artículo "The Signal Private Group System" de Chase, Perrin y Zaverucha.
poksho: Utilidades para implementar pruebas de conocimiento cero (como las utilizadas por zkgroup); significa "proof-of-knowledge, stateful-hash-object".
account-keys: Funcionalidad para usar consistentemente PINs como contraseñas en el sistema Secure Value Recovery de Signal, así como otras operaciones de claves a nivel de cuenta.
usernames: Funcionalidad para la generación, hashing y pruebas de nombres de usuario.
media: Utilidades para manipular medios.

Este repositorio es utilizado por las aplicaciones cliente de Signal (Android, iOS y Desktop) así como del lado del servidor. El uso fuera de Signal no está soportado. En particular, los productos de este repositorio son las bibliotecas Java, Swift y TypeScript que envuelven las implementaciones subyacentes en Rust. Todas las APIs e implementaciones están sujetas a cambios sin previo aviso, al igual que las capas de "puente" JNI, C y Node add-on. Sin embargo, los cambios incompatibles hacia atrás en las APIs de Java, Swift, TypeScript y Rust que no son de puente se reflejarán en el número de versión en la medida de lo posible, incluidos los aumentos a las versiones mínimas de herramientas soportadas.

Compilación

Instalación del toolchain

Para compilar cualquier cosa en este repositorio debes tener Rust instalado, así como versiones recientes de Clang, libclang, CMake, Make, protoc, Python (3.9+) y git.

Linux/Debian

En un sistema similar a Debian, puedes obtener estas dependencias adicionales a través de apt:

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

macOS

En macOS, tenemos un script mantenido con el mejor esfuerzo posible para configurar el toolchain de Rust que puedes ejecutar con:

$ bin/mac_setup.sh

Rust

Primera compilación y prueba

La compilación actualmente usa una versión específica del compilador estable de Rust, que será descargada automáticamente por cargo. Para compilar y probar las bibliotecas de protocolo básicas:

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

Herramientas adicionales de Rust

Las herramientas básicas anteriores deberían ser suficientes para la mayoría del desarrollo de libsignal en Rust.

Eventualmente, puede que descubras que necesitas algunas herramientas adicionales de Rust como taplo para el formateo de código.

Siempre debes instalar cualquier herramienta de Rust que necesites que pueda afectar la compilación desde cargo en lugar de desde tu gestor de paquetes del sistema (por ejemplo, apt o brew). Los gestores de paquetes a veces contienen versiones desactualizadas de estas herramientas que pueden romper la compilación con problemas de incompatibilidad (especialmente cbindgen).

Para instalar las principales dependencias adicionales de Rust que coincidan con las versiones que usamos, puedes ejecutar los siguientes comandos:

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

Java/Android

Configuración del toolchain

Para compilar para Android debes instalar varios paquetes adicionales, incluido un JDK, el NDK/SDK de Android, y agregar los targets de Android al compilador de Rust, usando

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

Nuestra versión de JDK soportada oficialmente para compilaciones de Android es JDK 21, así que asegúrate de instalar, por ejemplo, OpenJDK 21, y luego apuntar JAVA_HOME a él.

Puedes hacer esto fácilmente en macOS mediante:

export JAVA_HOME=$(/usr/libexec/java_home -v 21)

En Linux, la forma de hacer esto varía según la distribución. Para distribuciones basadas en Debian como Ubuntu, puedes usar:

sudo update-alternatives --config java

También incluimos un archivo .tools_version para usar con gestores de versiones en tiempo de ejecución.

Compilación y pruebas

Para compilar el jar y aar de Java/Android, y ejecutar las pruebas:

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

Puedes pasar -P debugLevelLogs a Gradle para compilar sin filtrar los logs de nivel debug y verbose de Rust, y -P jniTypeTagging para habilitar comprobaciones adicionales en el código de puente JNI de Rust.

Alternativamente, hay disponible un sistema de compilación que usa Docker:

$ cd java
$ make

Al exponer nuevas APIs a Java, necesitarás ejecutar rust/bridge/jni/bin/gen_java_decl.py además de recompilar. Esto requiere instalar la herramienta de Rust cbindgen, como se detalla arriba.

Uso como biblioteca

Signal publica paquetes Java para su propio uso, bajo los nombres org.signal:libsignal-server, org.signal:libsignal-client y org.signal:libsignal-android. libsignal-client y libsignal-server contienen bibliotecas nativas para Linux x86_64 de sabor Debian, así como Windows (x86_64) y macOS (x86_64 y arm64). libsignal-android contiene bibliotecas nativas para armeabi-v7a, arm64-v8a, x86 y x86_64 Android. Estas se encuentran en un repositorio Maven en https://build-artifacts.signal.org/libraries/maven/; para usarlas desde Gradle, agrega lo siguiente a tu bloque repositories:

maven {
  name = "SignalBuildArtifacts"
  // The "uri()" part is only necessary for Kotlin Gradle; Groovy Gradle accepts a bare string here.
  url = uri("https://build-artifacts.signal.org/libraries/maven/")
}

Las compilaciones anteriores se publicaban en Maven Central en su lugar.

Al compilar para Android necesitas tanto libsignal-android como libsignal-client, pero las bibliotecas de Windows y macOS en libsignal-client no se excluirán automáticamente de tu aplicación final. Puedes excluirlas explícitamente usando packaging:

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

Además puedes excluir libsignal_jni_testing.so si no planeas usar ninguna de las APIs destinadas a pruebas de cliente.

Probar una compilación local con Signal-Android

El archivo gradle.properties de Signal-Android tiene una línea comentada para incluir libsignal como parte de la compilación. Descomenta esa línea y ajusta la ruta; opcionalmente, puedes restringir las arquitecturas para las que quieres compilar agregando androidArchs=aarch64 al gradle.properties de libsignal. (El conjunto de arquitecturas reconocidas está en java/build_jni.sh.) Si estás usando un IDE, necesitarás reimportar la estructura de Gradle en este punto. Cuando termines, revierte los cambios en el gradle.properties de la aplicación Android y reimporta una vez más.

Ten en cuenta que esto no importa las partes en Rust del proyecto al IDE. Hacer eso en un IDE multilenguaje como IDEA es posible, pero complicado; a partir de 2025 la forma más confiable de hacerlo es abrir primero el proyecto Android, agregar el directorio raíz del repositorio libsignal como proyecto Rust en segundo lugar (incluyendo solo el directorio de nivel superior), y solo entonces hacer los cambios en gradle.properties.

Swift

Para aprender sobre el proceso de compilación de Swift, consulta swift/README.md

Node

Necesitarás Node instalado para compilar. Si tienes nvm, puedes ejecutar nvm use para seleccionar una versión apropiada automáticamente.

Usamos npm como nuestro gestor de paquetes, y un script de Python para controlar la compilación de la biblioteca Rust, accesible como npm run build.

$ cd node
$ nvm use
$ npm install
$ npm run build
$ npm run tsc
$ npm run test

Al probar cambios localmente, puedes usar npm run build para hacer una recompilación incremental de la biblioteca Rust. Alternativamente, npm run build-with-debug-level-logs recompilará sin filtrar los logs de nivel debug y verbose.

Al exponer nuevas APIs a Node, necesitarás ejecutar just generate-node además de recompilar.

NPM

Signal publica el paquete NPM @signalapp/libsignal-client para su propio uso, incluyendo bibliotecas nativas para Windows, macOS y Linux de sabor Debian. Se incluyen compilaciones tanto x64 como arm64 para las tres plataformas, pero las compilaciones arm64 para Windows y Linux se consideran experimentales, ya que no hay compilaciones oficiales de Signal para esas arquitecturas.

Probar una compilación local con Signal-Desktop

Después de ejecutar todos los comandos de compilación anteriores, ajusta la dependencia @signalapp/libsignal-client en el package.json de la aplicación Desktop a "link:path/to/libsignal/node" y ejecuta pnpm install. Cuando termines, revierte los cambios en package.json y ejecuta pnpm install de nuevo.

Contribuciones

Signal acepta contribuciones externas a este proyecto. Sin embargo, a menos que el cambio sea simple y fácil de entender, por ejemplo corregir un error o un problema de portabilidad, agregar una nueva prueba o mejorar el rendimiento, primero abre un issue para discutir el cambio que pretendes hacer, ya que no todos los cambios pueden ser aceptados.

Las contribuciones que no serán utilizadas directamente por una de las aplicaciones cliente oficiales de Signal aún pueden ser consideradas, pero solo si no representan una carga de mantenimiento indebida o entran en conflicto con los objetivos del proyecto.

Firmar un CLA (Contributor License Agreement) es obligatorio para todas las contribuciones.

Formateo de código y agradecimientos

Puedes ejecutar el formateador en todo el proyecto ejecutando:

just format-all

Puedes ejecutar pruebas más exhaustivas, así como linters y clippy, ejecutando:

just check-pre-commit

Al hacer un PR que ajusta dependencias, necesitarás regenerar nuestros archivos de agradecimientos. Consulta acknowledgments/README.md.

Aspectos legales

Aviso sobre criptografía

Esta distribución incluye software criptográfico. El país en el que resides actualmente puede tener restricciones sobre la importación, posesión, uso y/o reexportación a otro país de software de cifrado. ANTES de usar cualquier software de cifrado, por favor verifica las leyes, regulaciones y políticas de tu país en relación con la importación, posesión o uso, y reexportación de software de cifrado, para ver si esto está permitido. Consulta http://www.wassenaar.org/ para más información.

El Departamento de Comercio del Gobierno de EE. UU., Oficina de Industria y Seguridad (BIS), ha clasificado este software como Número de Control de Exportación de Mercancías (ECCN) 5D002.C.1, que incluye software de seguridad de la información que usa o realiza funciones criptográficas con algoritmos asimétricos. La forma y manera de esta distribución lo hace elegible para exportación bajo la excepción de Licencia ENC Technology Software Unrestricted (TSU) (ver las Regulaciones de Administración de Exportaciones de la BIS, Sección 740.13) tanto para código objeto como para código fuente.

Licencia

Licenciado bajo GNU AGPLv3: https://www.gnu.org/licenses/agpl-3.0.html

libsignal v0.102.2

Categorías