This is a ratcheting forward secrecy protocol that works in synchronous and asynchronous messaging environments. See the \href{https://github.com/whispersystems/libsignal-protocol-java}{\tt Java library} for more details.

\section*{Building libsignal-\/protocol-\/c}

\subsection*{Development host setup}

\subsubsection*{Build dependencies}


\begin{DoxyItemize}
\item \href{https://cmake.org/}{\tt C\+Make} 2.\+8.\+4 or higher
\item \href{https://libcheck.github.io/check/}{\tt Check $\ast$1}
\item \href{https://www.openssl.org/}{\tt Open\+S\+SL $\ast$1} 1.\+0 or higher
\begin{DoxyItemize}
\item On Mac\+OS X, \href{https://developer.apple.com/library/content/documentation/Security/Conceptual/cryptoservices/GeneralPurposeCrypto/GeneralPurposeCrypto.html}{\tt Common Crypto} is used instead of Open\+S\+SL
\end{DoxyItemize}
\item \href{http://ltp.sourceforge.net/coverage/lcov.php}{\tt L\+C\+OV $\ast$2}
\end{DoxyItemize}

Most of these dependencies are required just for the unit test suite and development of the library itself. When integrating into actual applications, you should not need anything beyond C\+Make. Alternatively, you may integrate the code using a build system of your choice. Items marked with $\ast$1 are required for tests, with $\ast$2 are additionally required for code coverage.

\subsubsection*{Setting up a fresh source tree}

\begin{DoxyVerb}$ cd /path/to/libsignal-protocol-c
$ mkdir build
$ cd build
$ cmake -DCMAKE_BUILD_TYPE=Debug ..
$ make
\end{DoxyVerb}


\subsubsection*{Running the unit tests}

\begin{DoxyVerb}$ cd /path/to/libsignal-protocol-c/build
$ cmake -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=1 ..
$ cd tests
$ make
$ cd ..
$ ctest
\end{DoxyVerb}


\subsubsection*{Creating the code coverage report}

\begin{DoxyVerb}$ cd /path/to/libsignal-protocol-c/build
$ cmake -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=1 -DCOVERAGE=1 ..
$ make coverage
\end{DoxyVerb}


The generated code coverage report can be found in\+: {\ttfamily /path/to/libsignal-\/protocol-\/c/build/coverage}

\subsubsection*{Eclipse project setup}

C\+Make provides a tutorial on Eclipse project setup here\+: \href{https://cmake.org/Wiki/CMake:Eclipse_UNIX_Tutorial}{\tt https\+://cmake.\+org/\+Wiki/\+C\+Make\+:\+Eclipse\+\_\+\+U\+N\+I\+X\+\_\+\+Tutorial}

It is recommended to follow the more manual \char`\"{}\+Option 2,\char`\"{} since the Eclipse project generator built into C\+Make tends to be outdated and leads you toward a very awkward and occasionally broken project configuration.

\subsubsection*{Protocol Buffers compiler}

This project uses serialization code based on \href{https://github.com/google/protobuf}{\tt Protocol Buffers}. Since the official library does not support C, the \href{https://github.com/protobuf-c/protobuf-c}{\tt protobuf-\/c} generator is used instead. For the sake of convenience, the generated code and its dependencies are included in the source tree. The generated code can be regenerated at any time by installing the two mentioned packages and running \char`\"{}make\char`\"{} in the \char`\"{}protobuf/\char`\"{} subdirectory.

\subsection*{Target platforms}

C\+Make toolchain files have been included from the following sources\+:


\begin{DoxyItemize}
\item \href{https://code.google.com/archive/p/ios-cmake}{\tt i\+OS}
\item \href{https://github.com/blackberry/OGRE/blob/master/src/CMake/toolchain/blackberry.toolchain.cmake}{\tt Black\+Berry 10}
\end{DoxyItemize}

\section*{Using libsignal-\/protocol-\/c}

\subsection*{Library initialization}

Before using the library, a libsignal-\/protocol-\/c client needs to initialize a global context. This global context is used to provide callbacks for implementations of functions used across the library that need client-\/specific implementations. Refer to \char`\"{}signal\+\_\+protocol.\+h\char`\"{} for detailed documentation on these functions, and the unit tests for example implementations.


\begin{DoxyCode}
\hyperlink{structsignal__context}{signal\_context} *global\_context;
\hyperlink{signal__protocol_8h_a0fefc02f9def73205022340f7fd1a2cb}{signal\_context\_create}(&global\_context, user\_data);
\hyperlink{signal__protocol_8h_a1e464669c9419eea988f556158a49d57}{signal\_context\_set\_crypto\_provider}(global\_context, &provider);
\hyperlink{signal__protocol_8h_a116e09ff4b2faae8aa8fcf5fa062598a}{signal\_context\_set\_locking\_functions}(global\_context, lock\_function, 
      unlock\_function);
\end{DoxyCode}


\subsection*{Client install time}

At install time, a libsignal-\/protocol-\/c client needs to generate its identity keys, registration id, and prekeys.


\begin{DoxyCode}
\hyperlink{signal__protocol__types_8h_a2b29fe6c645390a72526c774c35ad457}{ratchet\_identity\_key\_pair} *identity\_key\_pair;
\hyperlink{uthash_8h_a435d1572bf3f880d55459d9805097f62}{uint32\_t} registration\_id;
\hyperlink{signal__protocol__types_8h_af153890f9b52723e6cc43f3dff3b2ed6}{signal\_protocol\_key\_helper\_pre\_key\_list\_node} *pre\_keys\_head;
\hyperlink{signal__protocol__types_8h_a52e43d2d7af0b108957939886064be81}{session\_signed\_pre\_key} *signed\_pre\_key;

\hyperlink{key__helper_8h_ad2c413686d4122374039ea45b494beff}{signal\_protocol\_key\_helper\_generate\_identity\_key\_pair}(
      &identity\_key\_pair, global\_context);
\hyperlink{key__helper_8h_a2c69b0ecea5c387bdc42be354b7de387}{signal\_protocol\_key\_helper\_generate\_registration\_id}(&
      registration\_id, 0, global\_context);
\hyperlink{key__helper_8h_a00fc658a9224a87eb08eaebe4cc17903}{signal\_protocol\_key\_helper\_generate\_pre\_keys}(&pre\_keys\_head, 
      start\_id, 100, global\_context);
\hyperlink{key__helper_8h_a5bd3ab4ba84a14dee25fce1ebcaa1057}{signal\_protocol\_key\_helper\_generate\_signed\_pre\_key}(&
      signed\_pre\_key, identity\_key\_pair, 5, timestamp, global\_context);

\textcolor{comment}{/* Store identity\_key\_pair somewhere durable and safe. */}
\textcolor{comment}{/* Store registration\_id somewhere durable and safe. */}

\textcolor{comment}{/* Store pre keys in the pre key store. */}
\textcolor{comment}{/* Store signed pre key in the signed pre key store. */}
\end{DoxyCode}


The above example is simplified for the sake of clarity. All of these functions return errors on failure, and those errors should be checked for in real usage.

There are also iteration and serialization methods for the above types that should be used as appropriate.

\subsection*{Building a session}

A libsignal-\/protocol-\/c client needs to implement four data store callback interfaces\+: {\ttfamily \hyperlink{structsignal__protocol__identity__key__store}{signal\+\_\+protocol\+\_\+identity\+\_\+key\+\_\+store}}, {\ttfamily \hyperlink{structsignal__protocol__pre__key__store}{signal\+\_\+protocol\+\_\+pre\+\_\+key\+\_\+store}}, {\ttfamily \hyperlink{structsignal__protocol__signed__pre__key__store}{signal\+\_\+protocol\+\_\+signed\+\_\+pre\+\_\+key\+\_\+store}}, and {\ttfamily \hyperlink{structsignal__protocol__session__store}{signal\+\_\+protocol\+\_\+session\+\_\+store}}. These will manage loading and storing of identity, prekeys, signed prekeys, and session state.

These callback interfaces are designed such that implementations should treat all data flowing through them as opaque binary blobs. Anything necessary for referencing that data will be provided as separate function arguments to those callbacks. If it is ever necessary for clients to directly access stored data in terms of library data structures, they should use the accessor functions declared in \char`\"{}signal\+\_\+protocol.\+h\char`\"{} for these data stores.

Once the callbacks for these data stores are implemented, building a session is fairly straightforward\+:


\begin{DoxyCode}
\textcolor{comment}{/* Create the data store context, and add all the callbacks to it */}
\hyperlink{signal__protocol__types_8h_a407899f11766a172ae880601b8c3b4df}{signal\_protocol\_store\_context} *store\_context;
\hyperlink{signal__protocol_8h_ac17720b2167025e1d3368808a01de185}{signal\_protocol\_store\_context\_create}(&store\_context, context);
\hyperlink{signal__protocol_8h_a4ace03a45ac3f9ce7ca4ebab6ab97a5e}{signal\_protocol\_store\_context\_set\_session\_store}(
      store\_context, &session\_store);
\hyperlink{signal__protocol_8h_aea613bbb75c1404b132830b654ff9c85}{signal\_protocol\_store\_context\_set\_pre\_key\_store}(
      store\_context, &pre\_key\_store);
\hyperlink{signal__protocol_8h_aaad8dbbe3ff22fdee2e90277e82a7fa9}{signal\_protocol\_store\_context\_set\_signed\_pre\_key\_store}
      (store\_context, &signed\_pre\_key\_store);
\hyperlink{signal__protocol_8h_aa90fcd85fe954044eb9e2a47393d320c}{signal\_protocol\_store\_context\_set\_identity\_key\_store}(
      store\_context, &identity\_key\_store);

\textcolor{comment}{/* Instantiate a session\_builder for a recipient address. */}
\hyperlink{structsignal__protocol__address}{signal\_protocol\_address} address = \{
    \textcolor{stringliteral}{"+14159998888"}, 12, 1
\};
\hyperlink{signal__protocol__types_8h_aa997098aa1a29dee93a0e9836abe9e26}{session\_builder} *builder;
\hyperlink{session__builder_8h_ac21e975d8ddd4be36fe4f776e6fca67d}{session\_builder\_create}(&builder, store\_context, &address, global\_context);

\textcolor{comment}{/* Build a session with a pre key retrieved from the server. */}
\hyperlink{session__builder_8h_a082adee8735b34847b4822eaa7bbabf7}{session\_builder\_process\_pre\_key\_bundle}(builder, retrieved\_pre\_key);

\textcolor{comment}{/* Create the session cipher and encrypt the message */}
\hyperlink{signal__protocol__types_8h_a4a208c3e8a59fe1c41527b757e52f8b5}{session\_cipher} *cipher;
\hyperlink{session__cipher_8h_a48e09bee3587f661ffca3d4ac37970fa}{session\_cipher\_create}(&cipher, store\_context, &address, global\_context);

\hyperlink{signal__protocol__types_8h_abd86bf8290e33b6f12e5b7122085aab0}{ciphertext\_message} *encrypted\_message;
\hyperlink{session__cipher_8h_a6ae0c5876ea846029b26617f0a4e9ec1}{session\_cipher\_encrypt}(cipher, message, message\_len, &encrypted\_message);

\textcolor{comment}{/* Get the serialized content and deliver it */}
\hyperlink{structsignal__buffer}{signal\_buffer} *serialized = \hyperlink{protocol_8h_a116e6e50cc9d4e464dd89eb7688b694b}{ciphertext\_message\_get\_serialized}
      (encrypted\_message);

deliver(\hyperlink{signal__protocol_8h_ad7b6d0f65995ff6d3fbe8c0fa8148bbb}{signal\_buffer\_data}(serialized), \hyperlink{signal__protocol_8h_a8970783ebd66dc5b04d9a722d95e1927}{signal\_buffer\_len}(serialized));

\textcolor{comment}{/* Cleanup */}
\hyperlink{signal__protocol_8h_a24cc5948b7a156359945113bbee09786}{SIGNAL\_UNREF}(encrypted\_message);
\hyperlink{session__cipher_8h_ac25e6b707eeccd2fb4e4639c8c9e2b31}{session\_cipher\_free}(cipher);
\hyperlink{session__builder_8h_ab4a4e9b60dd3966ece495e6c91dd9c57}{session\_builder\_free}(builder);
\hyperlink{signal__protocol_8h_ad17110e922daad3b470eb9a7c854eb18}{signal\_protocol\_store\_context\_destroy}(store\_context);
\end{DoxyCode}


The above example is simplified for the sake of clarity. All of these functions return errors on failure, and those errors should be checked for in real usage.

\subsection*{Memory management notes}

For every custom data type that the libsignal-\/protocol-\/c library can allocate and return, a corresponding way of deallocating an instance of that data type is provided.

The more basic and higher level data types provide a type-\/specific free or destroy function. These types include {\ttfamily \hyperlink{structsignal__context}{signal\+\_\+context}}, {\ttfamily signal\+\_\+protocol\+\_\+store\+\_\+context}, {\ttfamily \hyperlink{structsignal__buffer}{signal\+\_\+buffer}}, {\ttfamily signal\+\_\+buffer\+\_\+list}, {\ttfamily signal\+\_\+int\+\_\+list}, {\ttfamily signal\+\_\+protocol\+\_\+key\+\_\+helper\+\_\+pre\+\_\+key\+\_\+list\+\_\+node}, {\ttfamily session\+\_\+builder}, {\ttfamily session\+\_\+cipher}, {\ttfamily group\+\_\+session\+\_\+builder}, {\ttfamily group\+\_\+cipher}, and {\ttfamily fingerprint\+\_\+generator}.

Most of the other data types, including everything internal, use a reference counting mechanism. If you are going to hold onto a reference to one of these types, use the {\ttfamily \hyperlink{signal__protocol_8h_afed628c1d3c8e27893b3ecd16118869b}{S\+I\+G\+N\+A\+L\+\_\+\+R\+E\+F(x)}} macro to increment its count. If you are done with a reference, use {\ttfamily \hyperlink{signal__protocol_8h_a24cc5948b7a156359945113bbee09786}{S\+I\+G\+N\+A\+L\+\_\+\+U\+N\+R\+E\+F(x)}} to decrement its count. When the count reaches 0, the type\textquotesingle{}s destructor function is called.

\section*{Legal things}

\subsection*{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. B\+E\+F\+O\+RE using any encryption software, please check your country\textquotesingle{}s laws, regulations and policies concerning the import, possession, or use, and re-\/export of encryption software, to see if this is permitted. See \href{http://www.wassenaar.org/}{\tt http\+://www.\+wassenaar.\+org/} for more information.

The U.\+S. Government Department of Commerce, Bureau of Industry and Security (B\+IS), has classified this software as Export Commodity Control Number (E\+C\+CN) 5\+D002.\+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 E\+NC Technology Software Unrestricted (T\+SU) exception (see the B\+IS Export Administration Regulations, Section 740.\+13) for both object code and source code.

\subsection*{License}

Copyright 2015-\/2016 Open Whisper Systems

Licensed under the G\+P\+Lv3\+: \href{http://www.gnu.org/licenses/gpl-3.0.html}{\tt http\+://www.\+gnu.\+org/licenses/gpl-\/3.\+0.\+html}

Additional Permissions For Submission to Apple App Store\+: Provided that you are otherwise in compliance with the G\+P\+Lv3 for each covered work you convey (including without limitation making the Corresponding Source available in compliance with Section 6 of the G\+P\+Lv3), Open Whisper Systems also grants you the additional permission to convey through the Apple App Store non-\/source executable versions of the Program as incorporated into each applicable covered work as Executable Versions only under the Mozilla Public License version 2.\+0 (\href{https://www.mozilla.org/en-US/MPL/2.0/}{\tt https\+://www.\+mozilla.\+org/en-\/\+U\+S/\+M\+P\+L/2.\+0/}). 