documentation

[Be-ing]

There currently isn't any API usage documentation. The README.md still says "Work in progress. Subject to change without notice, use outside Signal not yet recommended." so maybe it's not worthwhile to invest the effort in thorough documentation yet? Nevertheless at least a minimal getting started example for each language would be helpful.

[jack-signal]

At this point the library is not sufficient for actually developing a complete Signal client - a great deal of protocol logic is still embedded in the individual clients. In the future that will hopefully change and we'll consider our options for documentation and examples.

The Java binding closes matches libsignal-protocol-java and so that libs documentation may give some hints as to usage.

[Be-ing]

Thank you for clarifying. I didn't realize the clients were handling much of the protocol. It looks like the original libsignal-protocol-c is not very actively developed anymore so it wouldn't be a great idea to start a new client using that now. But this new library isn't quite ready yet either. Am I understanding that right?

[jack-signal]

I believe libsignal-protocol-c was originally written for Whatsapp. It's possible FB is still using it but I don't know. Signal is not using it in any of the clients and nobody here spends any time on it.

libsignal-protocol-java is relatively well tested, but, in recent releases the Android client has switched to using the Rust library instead. So it is unlikely that libsignal-protocol-java will see any further development. That said the low level protocol details encapsulated in the libsignal-protocol-{c,java} libraries do not change much.

If you want to build a complete Signal client, of the options available I think your best bet is this experimental, completely undocumented, work in progress, unsupported library. Unlike the C and Java libraries we are planning to expand this to cover a great deal of additional necessary client logic, and while we can't really offer much assistance to outside users, we'll at least respond to bug reports and can consider merging PRs, which is far more than you will get from the C or Java libs.

[Do note that this library is AGPLv3, while the libsignal-protocol-{c,java} libraries are GPLv3]

[Be-ing]

Great, thanks for clarifying again. I personally don't have the capacity to lead development of a new client (I already have one really complicated cross platform application to maintain). Because the Electron client maintainers consider feature parity with the Android and iOS client out of scope, there is interest in starting a new native client for Linux. It seems that using the C FFI of this new library would be the most maintainable way to implement that.

[Be-ing]

What is the relationship of this library to the zkgroup and ringrtc libraries? Are these all independent libraries used together by the clients? Is there a plan to integrate them into one library that handles all clients' protocol logic?

[Be-ing]

@hiqua I saw you 👍 'd my comment above. Are you interested in working on a native adaptive Linux client for Signal? I have started discussions on the Signal and Pine64 forums trying to organize people who are interested in working on this. Please comment on one of those if you're interested to avoid cluttering this issue tracker.

[Be-ing]

What features of the protocol does this library not implement yet? At least it seems that this can register an account and send & receive text messages. That would be the minimum to get a proof-of-concept application working which would serve most of my personal use cases and hopefully attract more developers to contribute.

IIUC this library only handles processing the messages, but it's up to the clients to do network I/O. Is that right?

[jrose-signal]

What is the relationship of this library to the zkgroup and ringrtc libraries? Are these all independent libraries used together by the clients? Is there a plan to integrate them into one library that handles all clients' protocol logic?

Yes, zkgroup, RingRTC, and libsignal-client are all used by the client apps. As far as combining them into one library: zkgroup predates this repo, but it's likely to be merged in to this one at some point. (As I noted in signalapp/zkgroup#13, "if it ain't broke, don't fix it" applies here, so it's not being prioritized right now.) RingRTC is a bit trickier because it incorporates Signal's fork of WebRTC, rather than being a pure-Rust library.

IIUC this library only handles processing the messages, but it's up to the clients to do network I/O. Is that right?

That's correct, and indeed it's only really processing the cryptography parts of the messages. The data that comes out of the network I/O still has to be parsed before you can hand the encrypted message part to libsignal-client (and similar for sending instead of receiving).

What features of the protocol does this library not implement yet? At least it seems that this can register an account and send & receive text messages. That would be the minimum to get a proof-of-concept application working which would serve most of my personal use cases and hopefully attract more developers to contribute.

This library does not do registration, or encoding and decoding of payloads inside the encryption (you can see the various message types currently in use). It might do some of those things in the future, since its goal is to support the official Signal client apps, but today it's mostly just implementing the cryptography layer.

[Be-ing]

Thanks for taking the time to respond. That helped clarify a lot. I've been discussing with @rubdos who has been working on rewriting Whisperfish in Rust, C++, and QML (it was originally written in Go). He and some others have implemented much of the client logic including the networking in the libsignal-service-rs Rust library. Currently it uses the old libsignal-protocol-c library but they intend to switch to this new Rust library.

Rather than me starting a new client from scratch, we'll be working together to decouple Whisperfish from Sailfish OS and implement an alternative GUI with KDE's adaptive Kirigami QML library so we can have a native Signal client for the new non-Android Linux smartphones (PinePhone and Librem 5). Some of the KDE Plasma Mobile developers are interested in assisting with this too. If anyone reading this is interested in helping, join us on Matrix at #whisperfish:rubdos.be

Would you be open to pull requests adding features to this library that you have not implemented? Or would you prefer that we use this library as part of our independent libsignal-service-rs library? Also, would you be open to pull requests adding documentation to this library? I understand if you want to hold off on documentation until you've stabilized the API. Let us know how we can collaborate. We're trying to architect this in a way that's maintainable for both us and you.

[jrose-signal]

As far as documentation goes, I think even though we've come a long way, we're still not quite stable, and the fact that the product of this repo is the Java/Swift/TypeScript APIs rather than the Rust APIs complicates it as well. Therefore I'd rather to continue to hold off on that…but I'll re-open the issue at this point to acknowledge that it's a "missing feature" of sorts.

For actual unimplemented features, I'd be concerned about adding code to this library that isn't exercised in one of the official Signal clients. If it's something small to make life easier, sure, as long as it doesn't impose an undue maintenance burden (especially if it comes with tests). For something that would be used by the official clients, it'd be best to check on a case-by-case basis; we're a small team at Signal too, and may not have the bandwidth to collaborate on a design for a feature we weren't planning to move to libsignal-client yet. In that case, we'd be blocking your progress.

So in practice, maybe start a thread or send a message on https://community.signalusers.org? (And tag me to make sure I get a notification about it.) I can't promise we'll have time, but if there is something that's mutually beneficial then it'd be a shame to miss out.

[rubdos]

Hey @jrose-signal, I imagine a few parts that are mutually beneficial to move into here. I'm quite sure that we can deduplicate (de-quintiplate (?) at this point) some code, and we can move it step-by-step from the tuple (libsignal-service-rs, Signal-Android, Signal-iOS, Signal Desktop) into here. I'm basically thinking everything that matches Aes in libsignal-service-rs: the profile cipher, the envelope cipher, sealed session cipher, and provisioning cipher.

All these are duplicated efforts in all of your and our different client libraries, and is a good, simple, unopinionated, and small starting point that all the different clients can gradually adapt to, whenever there's time. It wouldn't block us if it's not in here yet, and it doesn't really block you if it's already in here.

I'll make a forum post too (still have to create an account, shame on me) and tag you there, because this is now off-topic here. EDIT: I made a forum post, but it's in the moderator queue. EDIT2: here we go: https://community.signalusers.org/t/lets-join-forces-deduplicating-ios-android-node-code-into-libsignal-client/31667?u=rubdos

[jrose-signal]

(No real progress has been made here but the library can definitely be considered stable now.)

[0xSaksham]

If this issue is good for a beginner and involves technical writing, I can contribute to it. Just point me to resources necessary.

[rubdos]

@0xSaksham I think you're hitting a chicken-and-egg problem there. A starting point, I think, is to look at the work that @cosmicexplorer did before. Especially look at the pull requests that are merged or open: https://github.com/signalapp/libsignal/pulls?q=is%3Apr+author%3Acosmicexplorer Maybe you can infer a modus operandi from there. If you have any specific questions, I think the Whisperfish community will be happy to chat, although I'm not sure how much time we will find for it either.

Finding time is always the issue here, I fear.