Crate libsignal_protocol

A Rust interface to the libsignal-protocol-c library.

A ratcheting forward secrecy protocol that works in synchronous and asynchronous messaging environments.

Key Concepts

PreKeys

This protocol uses a concept called “PreKeys”. A PreKey is a keys::PublicKey and an associated unique ID which are stored together by a server. PreKeys can also be signed.

At install time, clients generate a single signed PreKey, as well as a large list of unsigned PreKeys, and transmit all of them to the server.

Sessions

The Signal Protocol is session-oriented. Clients establish a “session” which is then used for all subsequent encrypt/decrypt operations. There is no need to ever tear down a session once one has been established.

Sessions are established in one of three ways:

1. PreKeyBundle. A client that wishes to send a message to a recipient can establish a session by retrieving a PreKeyBundle for that recipient from the server.
2. PreKeySignalMessages. A client can receive a PreKeySignalMessage from a recipient and use it to establish a session.
3. KeyExchangeMessages. Two clients can exchange KeyExchange messages to establish a session.

State

An established session encapsulates a lot of state between two clients. That state is maintained in durable records which need to be kept for the life of the session.

State is kept in the following places:

1. Identity State. Clients will need to maintain the state of their own identity key pair, as well as identity keys received from other clients (saved in an IdentityKeyStore).
2. PreKey State. Clients will need to maintain the state of their generated PreKeys in a PreKeyStore.
3. Signed PreKey States. Clients will need to maintain the state of their signed PreKeys using a SignedPreKeyStore.
4. Session State. Clients will need to maintain the state of the sessions they have established using a SessionStore.

Modules

crypto

Underlying cryptographic routines.

keys

Elliptic curve cryptography keys.

messages

Common message types.

stores

Places to store Signal Protocol state.

Structs

Address

A reference-counted pointer to a signal address (recipient name, device ID tuple).

Buffer

A byte buffer (e.g. Vec<u8>).

Context

Global state and callbacks used by the library.

HMACBasedKeyDerivationFunction

Context for a HMAC-based Key Derivation Function.

PreKeyBundle

The session state used when sending a message to another user.

PreKeyBundleBuilder

A builder type for the PreKeyBundle.

SessionBuilder

Create a new session.

SessionCipher

The cipher context used for encryption.

SessionRecord

The serialized state of a session.

SessionState

The internal state associated with a session.

StoreContext

Something which contains state used by the signal protocol.

Enums

InternalError

Traits

FromInternalErrorCode

A helper trait for going from an InternalError to a Result.

IntoInternalErrorCode

A helper trait for going from a Result to an InternalError.

Serializable

A helper trait for something which can be serialized to protobufs.

Functions

calculate_signature

Calculate the signature for a message.

create_hkdf

Create a new HMAC-based key derivation function.

generate_identity_key_pair

A helper function for generating a new IdentityKeyPair.

generate_key_pair

Generate a normal elliptic curve key pair.

generate_pre_keys

Generate a list of PreKeys. Clients should do this at install time, and subsequently any time the list of PreKeys stored on the server runs low.

generate_registration_id

Generate a new registration ID.

generate_signed_pre_key

Generate a signed pre-key.

session_builder

Create a new session builder for communication with the user with the specified address.

store_context

Create a container for the state used by the signal protocol.