BibleSync

From CrossWire Bible Society
Jump to: navigation, search

BibleSync is a multicast protocol to support Bible software shared co-navigation. It uses LAN multicast in either a personal/small team mutual navigation motif or in a classroom environment where there are Speakers plus the Audience. The library implementing the protocol is a single C++ class providing a complete yet minimal public interface to support mode setting, setup for packet reception, transmit on local navigation, and handling of incoming packets.

This library is not specific to any particular Bible software framework, completely agnostic as to structure of layers above BibleSync, and is not a product of The Sword Project. But its first implementation has been grafted into Xiphos.

History

BibleSync is a protocol first proposed by Costas Stergiou of theWord and, along with William Mills, wrote a version 1 draft specification. This draft appears not to have wide distribution, but in October 2012 a version 2 specification was sent around by Mills to a number of people with particular interest in widely-known Bible applications including theWord, BibleAnalyzer, Accordance, and Laridian. Karl Kleinpaste was among those reached as the contact point for Xiphos. Comments were taken about the v2 specification, but an update was not made available until September 2013. Response to that update was vast silence.

In March 2014, Karl took a personal interest in the updated v2. The specification still had some considerable rough edges and Karl took a number of liberties with it based on his networking background, with the intent of producing an updated specification that would reflect the changes that had been necessary. An initial implementation only for the Linux platform was produced by mid-April, as an integrated part of Xiphos. A bare level of Windows compatibility was then added, and Xiphos 3.2.0 was released in the 1st week of May 2014 with BibleSync capability.

At this time, the protocol offered 2 message types: A presence announcement, to inform other applications of participants in the conversation, and a synchronization message, to drive other listening applications. There is no security or privacy provided in the protocol, but it supports a passphrase as a conversation discriminant in the event that more than one BibleSync conversation occurs over a single LAN. Fundamentally, the protocol operates in either a Personal peer-among-peers mode, where each application drives all the others, or in a speaker/audience motif, where one or more Speakers navigate and the Audience applications listen and respond in kind. The difference is entirely within the matter of which half of the conversation (transmitting or receiving navigation synchronization) the application uses. Speaker and Audience each carry out half, transmitting or receiving, while the general Personal mode is both transmitter and receiver. This is to say, an application in Personal mode is both Speaker and Audience.

In May 2014, the protocol facility proper was then excised from Xiphos, becoming an independent library available for use by any application; it is not specific to Sword Project applications. What is necessary in the application is the "glue" code to interface with the library plus enough user interface to control the protocol use according to the wishes of the user. BibleSync has a code repository at github.com under Karl's management. Xiphos 3.2.1 was released in early June 2014 with the new library structure in place.

During the period from early April to mid-June 2014, Karl engaged the others who were part of the initial inquiries about the v2 specification, first to see if any others had produced an implementation, and then to garner discussion about the future of the protocol and the developing code base. No other implementation yet existed. There was considerable, lively discussion over the course of about 8 weeks.

Tim Morton of BibleAnalyzer took the offered implementation and began to experiment with it. He did some work in Python and found it workable but mentioned the problem that it was too easy to mis-start BibleSync in an application that would inadvertently drive others, i.e. the "grandma case": Give your grandmother a BibleSync-capable application on her iPhone or Android and send her to church where the pastor will use a BibleSync-capable application to drive teaching. If she can inadvertently (or even maliciously :-) start driving others' applications by not selecting Audience mode, then there is a problem.

This was discussed briefly and Karl chose a beacon-based enhancement to the protocol, where would-be Speakers must regularly announce their availability, and Audience applications can select which beacon-announced Speakers are to be heard and allowed to navigate.

The beacon enhancement was part of the excision from Xiphos integration and is part of how the implementation exists today. The use of beacons is not universally approved. Email discussion among the participants ranged widely, some in approval while others claimed that beacons would cause handheld devices to consume too much power, with which Karl disagreed on grounds that it is a single packet sent only every few seconds by a live application that the user has specifically requested, and when the device goes idle, the application will go to sleep and stop transmitting.

Significantly, no other participants in the conversation have ever offered either updates to the existing github codebase or a competing implementation in order that the benefits and costs of each might be considered, toward the goal of picking one as the base for future work. Therefore Karl's implementation stands as the single working, deployed, real world implementation.

By late June 2014, discussion among the email participants had gone silent. Nothing more has been said. Development of the library continues, with small bug fixes and anti-spoofing improvements. Notable was the adjustment of the specification in 2018 for a new chat message capability, intended as free-form text to be informally shared among participants by whatever UI methodology the application designer wishes. An unexpected failure of the default route discovery code led to an important re-write there in 2020.

Protocol details

BibleSync communicates using local multicast. Three operational modes are provided: Personal, Speaker, or Audience.

In Personal mode, BibleSync operates as a peer among peers, both sending and receiving navigation synchronization on the shared local multicast network. Applications are expected to respond appropriately to navigation, and to send synchronization events of their own as the user moves about his Bible.

In Speaker or Audience mode, BibleSync either transmits only (Speaker) or receives only (Audience) navigation. The Audience is expected to follow along with the Speaker's direction. The Speaker ignores incoming navigation; the Audience transmits no navigation.

The protocol is based on single packet transmissions, specifically intended to fit within one MSS of a typical Ethernet. There are 4 packet types defined: Presence announcement, Speaker beacon, navigation synchronization, and chat message. The packet format consists of a number of header fields followed by a series of name=value parameters terminated by newlines. A UUID is part of the packet definition. The header is 32 bytes and the UUID (16 bytes) is aligned to the latter half. Maximum size is 1280 bytes. A protocol version identifier, currently 3, is present as well as a packet type indicator. The specification makes allowance for possible future use of a multi-packet methodology but at the moment the packet count and packet index are required to be 1 and 0, respectively, with the possibility of this being enhanced if the protocol specification should see future discussion. The packet also includes a magic number to add certainty that the packet is intended for this protocol.

After the header, name=value pairs identify a number of required fields. Presence announcement and beacon are distinguished only by the packet type and are otherwise identical. Synchronization packets have additional fields to specify a Bible, a verse reference, and a few other utility fields. Note that BibleSync transmits references, not content. All packets identify the user, the application, the passphrase, and may optionally identify as well the application version and the device on which the application runs.

On startup of the protocol, BibleSync transmits a presence announcement, informing other communication partners of the application's participation. BibleSync makes this announcement available to the application; whether the application shows these announcements to the user is the application designer's choice.

Thereafter, as appropriate to the operational mode selected, BibleSync is tasked with polled reception of incoming navigation event packets and transmission of navigation event packets on the user's part.

Transmitters (Personal and Speaker modes) issue availability beacons every 10 seconds. Initial received beacons for previously-unknown Speakers are handed up to the application. These beacons provide for receivers (Personal and Audience modes) to maintain a managed list of available Speakers. Furthermore, when a transmitter ceases to issue beacons, its presence in the library's list of available Speakers is aged out until being removed after 30 seconds of beacon silence. The application is again informed when a Speaker goes dead.

Default listening behavior is that the first Speaker heard via beacon is marked for listening. Other transmitters claiming Speaker status via beacon are recognized and remembered but initially ignored, with their presence made known to the application. This provides for the application to maintain a list from which the user can select Speakers he wishes to synchronize his application. This default "first Speaker only" policy can be overridden by the application with any other policy desired.

Synchronization events include 5 data elements: The Bible abbreviation; the verse reference; an alternate reference (if desired; not required) which may allow the application to interpret better based on variant versification; a synchronization group identifier; and the domain.

The group identifier is a single ASCII digit between 1 and 9. The specification is imprecise as to this parameter's use. The initial interface with BibleSync in Xiphos uses the synchronization group as an indicator of the tab number in its tabbed interface: Not only is the Bible navigated, but the tab in which to navigate is selected.

The domain parameter is currently fixed as "BIBLE-VERSE". This may be put to greater use if there are ever future revisions of the protocol.

BibleSync transmits no packet when the application leaves the conversation.

Reference syntax

Applications must ensure that the references they send via BibleSync are sensible. In particular, Sword applications are fairly forgiving about reference syntax, but other applications may not be. Therefore it is imperative that applications ship only standards-compliant references. The protocol itself does not enforce any particular format, but the specification references BibleRef and OSIS.

Sharing multiple references

The point of the protocol is to ship a reference indicator for navigation by the receiving audience. This reference need not be a single verse. It could be a multiple reference generated by a search, a list from a Bible's cross reference, or a bookmark set maintained by the user in his application.

The limitation on how much can be shared is the maximum packet size of 1280 bytes. With basic overhead plus other name=value requirements in the packet, this leaves around 1000 or 1100 bytes in which to pack references. The implementation will take an arbitrarily large string for the reference, trimming it to fit the packet size limitation.

Security implications

BibleSync is a protocol defined for a friendly environment. That said, beacons had to be deployed because of the risk of a malicious or stupid user causing improper navigation in others' applications. Beyond that, there are a couple of implications, both in the realm of avoidance of impersonation.

(1) It would be possible for any malicious user to generate his own navigation packets using a legitimate Speaker's UUID. Therefore the protocol must retain information about every legitimate Speaker from his beacons so as to be able to verify the origin. This is to say, the implementation makes sure the UUID offered in navigation packets is always coming from the right origin IP address, as indicated by ongoing beacons.

(2) The first beacon needs to be transmitted before the presence announcement, in order to lay proper claim to a position as Speaker. If the presence announcement is transmitted first, then a malicious user could use that UUID to begin transmitting beacons and navigation from his own (different) IP address, unseating the legitimate Speaker. By sending the first beacon before the presence announcement, this is prevented.

Current state

At this time, Karl manages the github code repository. Help from Greg Hellings has kept the process of building the code for public use in a sane state, especially in its dependence on CMake. Release 1.1.2 was made on Christmas Eve 2014. A complete, updated specification including beacons and other matters beyond the original v2 specification is part of the source tree, along with a UNIX-style manual page, biblesync(7), for programmer reference.

The chat message capability induced version 2.0 in 2018, and a low-level update to re-work default route discovery led to 2.1 in 2020, which is where BibleSync stands today.

The entirety of the implementation is in the public domain.

Although a number of the early participants claimed an interest in deploying BibleSync, only Tim Morton is known to have experimented directly.

Inquiries to other Sword Project application developers showed interest from the authors of at least Bibledit and PocketSword.

External links

Retrieved from "https://wiki.crosswire.org/index.php?title=BibleSync&oldid=17128"