2019-05-02 02:31:23 +02:00
|
|
|
# Olm
|
2015-06-26 18:55:32 +02:00
|
|
|
|
2016-07-16 21:56:29 +02:00
|
|
|
An implementation of the Double Ratchet cryptographic ratchet described by
|
2017-06-08 05:12:53 +02:00
|
|
|
https://whispersystems.org/docs/specifications/doubleratchet/, written in C and
|
|
|
|
C++11 and exposed as a C API.
|
2015-06-26 18:55:32 +02:00
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
The specification of the Olm ratchet can be found in [docs/olm.md](docs/olm.md).
|
2016-10-19 20:14:18 +02:00
|
|
|
|
|
|
|
This library also includes an implementation of the Megolm cryptographic
|
2019-05-02 02:31:23 +02:00
|
|
|
ratchet, as specified in [docs/megolm.md](docs/megolm.md).
|
2015-10-03 00:57:46 +02:00
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
## Building
|
2015-06-26 18:55:32 +02:00
|
|
|
|
2018-10-22 21:28:09 +02:00
|
|
|
To build olm as a shared library run either:
|
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
```bash
|
|
|
|
cmake . -Bbuild
|
|
|
|
cmake --build build
|
|
|
|
```
|
2018-10-22 21:28:09 +02:00
|
|
|
|
|
|
|
or:
|
2015-06-26 18:55:32 +02:00
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
```bash
|
|
|
|
make
|
|
|
|
```
|
2015-06-26 18:55:32 +02:00
|
|
|
|
2018-10-22 21:28:09 +02:00
|
|
|
Using cmake is the preferred method for building the shared library; the
|
|
|
|
Makefile may be removed in the future.
|
|
|
|
|
|
|
|
To run the tests when using cmake, run:
|
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
```bash
|
|
|
|
cd build/tests
|
|
|
|
ctest .
|
|
|
|
```
|
2018-10-22 21:28:09 +02:00
|
|
|
To run the tests when using make, run:
|
2015-06-26 18:55:32 +02:00
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
```bash
|
|
|
|
make test
|
|
|
|
```
|
2015-06-26 18:55:32 +02:00
|
|
|
|
2018-10-22 21:25:56 +02:00
|
|
|
To build the JavaScript bindings, install emscripten from http://kripken.github.io/emscripten-site/ and then run:
|
2015-06-26 18:55:32 +02:00
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
```bash
|
|
|
|
make js
|
|
|
|
```
|
2017-01-17 10:58:13 +01:00
|
|
|
|
2018-10-10 20:40:01 +02:00
|
|
|
Note that if you run emscripten in a docker container, you need to pass through
|
|
|
|
the EMCC_CLOSURE_ARGS environment variable.
|
|
|
|
|
2016-12-20 10:42:06 +01:00
|
|
|
To build the android project for Android bindings, run:
|
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
```bash
|
|
|
|
cd android
|
|
|
|
./gradlew clean assembleRelease
|
|
|
|
```
|
2015-06-26 18:55:32 +02:00
|
|
|
|
2016-11-17 14:03:15 +01:00
|
|
|
To build the Xcode workspace for Objective-C bindings, run:
|
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
```bash
|
|
|
|
cd xcode
|
|
|
|
pod install
|
|
|
|
open OLMKit.xcworkspace
|
|
|
|
```
|
2016-11-17 14:03:15 +01:00
|
|
|
|
2018-10-22 21:28:09 +02:00
|
|
|
To build the Python bindings, first build olm as a shared library as above, and
|
|
|
|
then run:
|
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
```bash
|
|
|
|
cd python
|
|
|
|
make
|
|
|
|
```
|
2018-10-22 21:28:09 +02:00
|
|
|
|
|
|
|
to make both the Python 2 and Python 3 bindings. To make only one version, use
|
|
|
|
``make olm-python2`` or ``make olm-python3`` instead of just ``make``.
|
|
|
|
|
|
|
|
To build olm as a static library (which still needs libstdc++ dynamically) run
|
|
|
|
either:
|
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
```bash
|
|
|
|
cmake . -Bbuild -DBUILD_SHARED_LIBS=NO
|
|
|
|
cmake --build build
|
|
|
|
```
|
2018-10-22 21:28:09 +02:00
|
|
|
|
|
|
|
or
|
2017-03-16 20:20:16 +01:00
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
```bash
|
|
|
|
make static
|
|
|
|
```
|
2017-03-16 20:20:16 +01:00
|
|
|
|
2018-10-22 21:28:09 +02:00
|
|
|
The library can also be used as a dependency with CMake using:
|
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
```cmake
|
|
|
|
find_package(Olm::Olm REQUIRED)
|
|
|
|
target_link_libraries(my_exe Olm::Olm)
|
|
|
|
```
|
2018-10-22 21:28:09 +02:00
|
|
|
|
2020-06-11 17:25:52 +02:00
|
|
|
## Bindings
|
|
|
|
|
|
|
|
libolm can be used in different environments using bindings. In addition to the
|
|
|
|
JavaScript, Python, Java (Android), and Objective-C bindings included in this
|
|
|
|
repository, some bindings are (in alphabetical order):
|
|
|
|
|
2021-03-02 22:13:39 +01:00
|
|
|
- [cl-megolm](https://github.com/K1D77A/cl-megolm) (MIT) Common Lisp bindings
|
2021-06-17 16:19:38 +02:00
|
|
|
- [dart-olm](https://gitlab.com/famedly/company/frontend/libraries/dart-olm) (AGPLv3) Dart bindings
|
2020-06-11 17:25:52 +02:00
|
|
|
- [Dhole/go-olm](https://github.com/Dhole/go-olm) (Apache-2.0) Go bindings
|
2021-08-26 03:50:33 +02:00
|
|
|
- [jOlm](https://github.com/brevilo/jolm) (Apache-2.0) Java bindings
|
2020-06-11 17:25:52 +02:00
|
|
|
- [libQtOlm](https://gitlab.com/b0/libqtolm/) (GPLv3) Qt bindings
|
|
|
|
- [matrix-kt](https://github.com/Dominaezzz/matrix-kt) (Apache-2.0) Kotlin
|
|
|
|
library for Matrix, including Olm methods
|
|
|
|
- [maunium.net/go/mautrix/crypto/olm](https://github.com/tulir/mautrix-go/tree/master/crypto/olm)
|
|
|
|
(Apache-2.0) fork of Dhole/go-olm
|
2021-01-14 18:40:52 +01:00
|
|
|
- [nim-olm](https://gitea.com/BarrOff/nim-olm) (MIT) Nim bindings
|
2020-06-11 17:25:52 +02:00
|
|
|
- [olm-sys](https://gitlab.gnome.org/BrainBlasted/olm-sys) (Apache-2.0) Rust
|
|
|
|
bindings
|
|
|
|
|
2021-03-02 22:13:39 +01:00
|
|
|
Note that bindings may have a different license from libolm, and are *not*
|
|
|
|
endorsed by the Matrix.org Foundation C.I.C.
|
2020-06-11 17:25:52 +02:00
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
## Release process
|
2015-12-03 19:10:43 +01:00
|
|
|
|
2018-10-12 22:15:16 +02:00
|
|
|
First: bump version numbers in ``common.mk``, ``CMakeLists.txt``,
|
2021-04-06 17:18:50 +02:00
|
|
|
``javascript/package.json``, ``python/olm/__version__.py``, ``OLMKit.podspec``, ``Package.swift``,
|
2021-05-24 16:27:28 +02:00
|
|
|
and ``android/olm-sdk/src/main/java/org/matrix/olm/OlmManager.java`` in function ``getVersion()```.
|
2016-12-22 16:02:43 +01:00
|
|
|
|
2020-10-06 20:47:43 +02:00
|
|
|
Also, ensure the changelog is up to date, and that everything is committed to
|
2016-12-22 16:02:43 +01:00
|
|
|
git.
|
2016-09-14 12:48:15 +02:00
|
|
|
|
2016-12-22 16:02:43 +01:00
|
|
|
It's probably sensible to do the above on a release branch (``release-vx.y.z``
|
|
|
|
by convention), and merge back to master once the release is complete.
|
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
```bash
|
|
|
|
make clean
|
2017-01-17 11:03:13 +01:00
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
# build and test C library
|
|
|
|
make test
|
2016-12-22 16:02:43 +01:00
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
# build and test JS wrapper
|
|
|
|
make js
|
2021-05-04 23:54:05 +02:00
|
|
|
(cd javascript && \
|
|
|
|
npm run test && \
|
|
|
|
sha256sum olm.js olm_legacy.js olm.wasm > checksums.txt && \
|
|
|
|
gpg -b -a -u F75FDC22C1DE8453 checksums.txt && \
|
|
|
|
npm publish)
|
2016-12-22 16:02:43 +01:00
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
VERSION=x.y.z
|
|
|
|
git tag $VERSION -s
|
|
|
|
git push --tags
|
2016-12-22 16:02:43 +01:00
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
# OLMKit CocoaPod release
|
|
|
|
# Make sure the version OLMKit.podspec is the same as the git tag
|
|
|
|
# (this must be checked before git tagging)
|
|
|
|
pod spec lint OLMKit.podspec --use-libraries --allow-warnings
|
|
|
|
pod trunk push OLMKit.podspec --use-libraries --allow-warnings
|
|
|
|
# Check the pod has been successully published with:
|
|
|
|
pod search OLMKit
|
|
|
|
```
|
2016-07-11 15:51:04 +02:00
|
|
|
|
2021-05-04 23:54:05 +02:00
|
|
|
Python and JavaScript packages are published to the registry at
|
|
|
|
<https://gitlab.matrix.org/matrix-org/olm/-/packages>. The GitLab
|
|
|
|
documentation contains instructions on how to set up twine (Python) and npm
|
|
|
|
(JavaScript) to upload to the registry.
|
|
|
|
|
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
## Design
|
2015-06-26 18:55:32 +02:00
|
|
|
|
2015-06-27 01:15:23 +02:00
|
|
|
Olm is designed to be easy port to different platforms and to be easy
|
2015-06-26 18:55:32 +02:00
|
|
|
to write bindings for.
|
|
|
|
|
2016-05-13 12:36:41 +02:00
|
|
|
It was originally implemented in C++, with a plain-C layer providing the public
|
|
|
|
API. As development has progressed, it has become clear that C++ gives little
|
|
|
|
advantage, and new functionality is being added in C, with C++ parts being
|
|
|
|
rewritten as the need ariases.
|
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
### Error Handling
|
2015-06-26 18:55:32 +02:00
|
|
|
|
2015-06-27 01:15:23 +02:00
|
|
|
All C functions in the API for olm return ``olm_error()`` on error.
|
2015-06-26 18:55:32 +02:00
|
|
|
This makes it easy to check for error conditions within the language bindings.
|
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
### Random Numbers
|
2015-06-26 18:55:32 +02:00
|
|
|
|
2015-06-27 01:15:23 +02:00
|
|
|
Olm doesn't generate random numbers itself. Instead the caller must
|
2015-06-26 18:55:32 +02:00
|
|
|
provide the random data. This makes it easier to port the library to different
|
|
|
|
platforms since the caller can use whatever cryptographic random number
|
|
|
|
generator their platform provides.
|
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
### Memory
|
2015-06-26 18:55:32 +02:00
|
|
|
|
2015-06-27 01:15:23 +02:00
|
|
|
Olm avoids calling malloc or allocating memory on the heap itself.
|
2015-06-26 18:55:32 +02:00
|
|
|
Instead the library calculates how much memory will be needed to hold the
|
|
|
|
output and the caller supplies a buffer of the appropriate size.
|
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
### Output Encoding
|
2015-06-26 18:55:32 +02:00
|
|
|
|
|
|
|
Binary output is encoded as base64 so that languages that prefer unicode
|
|
|
|
strings will find it easier to handle the output.
|
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
### Dependencies
|
2015-06-26 18:55:32 +02:00
|
|
|
|
2015-06-27 01:15:23 +02:00
|
|
|
Olm uses pure C implementations of the cryptographic primitives used by
|
2015-06-26 18:55:32 +02:00
|
|
|
the ratchet. While this decreases the performance it makes it much easier
|
|
|
|
to compile the library for different architectures.
|
2015-06-27 01:15:23 +02:00
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
## Contributing
|
2017-01-17 11:07:45 +01:00
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
Please see [CONTRIBUTING.md](CONTRIBUTING.md) when making contributions to the library.
|
|
|
|
|
|
|
|
## Security assessment
|
2017-05-08 12:35:50 +02:00
|
|
|
|
|
|
|
Olm 1.3.0 was independently assessed by NCC Group's Cryptography Services
|
|
|
|
Practive in September 2016 to check for security issues: you can read all
|
|
|
|
about it at
|
2021-05-04 15:03:27 +02:00
|
|
|
https://www.nccgroup.com/globalassets/our-research/us/public-reports/2016/november/ncc_group_olm_cryptogrpahic_review_2016_11_01.pdf
|
2017-05-08 12:35:50 +02:00
|
|
|
and https://matrix.org/blog/2016/11/21/matrixs-olm-end-to-end-encryption-security-assessment-released-and-implemented-cross-platform-on-riot-at-last/
|
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
## Bug reports
|
|
|
|
|
2017-03-13 12:55:33 +01:00
|
|
|
Please file bug reports at https://github.com/matrix-org/olm/issues
|
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
## What's an olm?
|
2015-06-27 01:15:23 +02:00
|
|
|
|
|
|
|
It's a really cool species of European troglodytic salamander.
|
2016-05-13 13:54:30 +02:00
|
|
|
http://www.postojnska-jama.eu/en/come-and-visit-us/vivarium-proteus/
|
2015-10-05 15:21:08 +02:00
|
|
|
|
2019-05-02 02:31:23 +02:00
|
|
|
## Legal Notice
|
2015-10-05 15:21:08 +02:00
|
|
|
|
|
|
|
The software may be subject to the U.S. export control laws and regulations
|
|
|
|
and by downloading the software the user certifies that he/she/it is
|
|
|
|
authorized to do so in accordance with those export control laws and
|
|
|
|
regulations.
|