Convert README.rst to markdown
Signed-off-by: Aaron Raimist <aaron@raim.ist>
This commit is contained in:
parent
73288e6f2a
commit
b46ac91928
1 changed files with 80 additions and 95 deletions
|
@ -1,78 +1,75 @@
|
||||||
Olm
|
# Olm
|
||||||
===
|
|
||||||
|
|
||||||
An implementation of the Double Ratchet cryptographic ratchet described by
|
An implementation of the Double Ratchet cryptographic ratchet described by
|
||||||
https://whispersystems.org/docs/specifications/doubleratchet/, written in C and
|
https://whispersystems.org/docs/specifications/doubleratchet/, written in C and
|
||||||
C++11 and exposed as a C API.
|
C++11 and exposed as a C API.
|
||||||
|
|
||||||
The specification of the Olm ratchet can be found in `<docs/olm.rst>`_.
|
The specification of the Olm ratchet can be found in [docs/olm.md](docs/olm.md).
|
||||||
|
|
||||||
This library also includes an implementation of the Megolm cryptographic
|
This library also includes an implementation of the Megolm cryptographic
|
||||||
ratchet, as specified in `<docs/megolm.rst>`_.
|
ratchet, as specified in [docs/megolm.md](docs/megolm.md).
|
||||||
|
|
||||||
Building
|
## Building
|
||||||
--------
|
|
||||||
|
|
||||||
To build olm as a shared library run either:
|
To build olm as a shared library run either:
|
||||||
|
|
||||||
.. code:: bash
|
```bash
|
||||||
|
cmake . -Bbuild
|
||||||
cmake . -Bbuild
|
cmake --build build
|
||||||
cmake --build build
|
```
|
||||||
|
|
||||||
or:
|
or:
|
||||||
|
|
||||||
.. code:: bash
|
```bash
|
||||||
|
make
|
||||||
make
|
```
|
||||||
|
|
||||||
Using cmake is the preferred method for building the shared library; the
|
Using cmake is the preferred method for building the shared library; the
|
||||||
Makefile may be removed in the future.
|
Makefile may be removed in the future.
|
||||||
|
|
||||||
To run the tests when using cmake, run:
|
To run the tests when using cmake, run:
|
||||||
|
|
||||||
.. code:: bash
|
```bash
|
||||||
|
cd build/tests
|
||||||
cd build/tests
|
ctest .
|
||||||
ctest .
|
```
|
||||||
|
|
||||||
To run the tests when using make, run:
|
To run the tests when using make, run:
|
||||||
|
|
||||||
.. code:: bash
|
```bash
|
||||||
|
make test
|
||||||
make test
|
```
|
||||||
|
|
||||||
To build the JavaScript bindings, install emscripten from http://kripken.github.io/emscripten-site/ and then run:
|
To build the JavaScript bindings, install emscripten from http://kripken.github.io/emscripten-site/ and then run:
|
||||||
|
|
||||||
.. code:: bash
|
```bash
|
||||||
|
make js
|
||||||
make js
|
```
|
||||||
|
|
||||||
Note that if you run emscripten in a docker container, you need to pass through
|
Note that if you run emscripten in a docker container, you need to pass through
|
||||||
the EMCC_CLOSURE_ARGS environment variable.
|
the EMCC_CLOSURE_ARGS environment variable.
|
||||||
|
|
||||||
To build the android project for Android bindings, run:
|
To build the android project for Android bindings, run:
|
||||||
|
|
||||||
.. code:: bash
|
```bash
|
||||||
|
cd android
|
||||||
cd android
|
./gradlew clean assembleRelease
|
||||||
./gradlew clean assembleRelease
|
```
|
||||||
|
|
||||||
To build the Xcode workspace for Objective-C bindings, run:
|
To build the Xcode workspace for Objective-C bindings, run:
|
||||||
|
|
||||||
.. code:: bash
|
```bash
|
||||||
|
cd xcode
|
||||||
cd xcode
|
pod install
|
||||||
pod install
|
open OLMKit.xcworkspace
|
||||||
open OLMKit.xcworkspace
|
```
|
||||||
|
|
||||||
To build the Python bindings, first build olm as a shared library as above, and
|
To build the Python bindings, first build olm as a shared library as above, and
|
||||||
then run:
|
then run:
|
||||||
|
|
||||||
.. code:: bash
|
```bash
|
||||||
|
cd python
|
||||||
cd python
|
make
|
||||||
make
|
```
|
||||||
|
|
||||||
to make both the Python 2 and Python 3 bindings. To make only one version, use
|
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``.
|
``make olm-python2`` or ``make olm-python3`` instead of just ``make``.
|
||||||
|
@ -80,27 +77,25 @@ to make both the Python 2 and Python 3 bindings. To make only one version, use
|
||||||
To build olm as a static library (which still needs libstdc++ dynamically) run
|
To build olm as a static library (which still needs libstdc++ dynamically) run
|
||||||
either:
|
either:
|
||||||
|
|
||||||
.. code:: bash
|
```bash
|
||||||
|
cmake . -Bbuild -DBUILD_SHARED_LIBS=NO
|
||||||
cmake . -Bbuild -DBUILD_SHARED_LIBS=NO
|
cmake --build build
|
||||||
cmake --build build
|
```
|
||||||
|
|
||||||
or
|
or
|
||||||
|
|
||||||
.. code:: bash
|
```bash
|
||||||
|
make static
|
||||||
make static
|
```
|
||||||
|
|
||||||
The library can also be used as a dependency with CMake using:
|
The library can also be used as a dependency with CMake using:
|
||||||
|
|
||||||
.. code:: cmake
|
```cmake
|
||||||
|
find_package(Olm::Olm REQUIRED)
|
||||||
|
target_link_libraries(my_exe Olm::Olm)
|
||||||
|
```
|
||||||
|
|
||||||
find_package(Olm::Olm REQUIRED)
|
## Release process
|
||||||
target_link_libraries(my_exe Olm::Olm)
|
|
||||||
|
|
||||||
|
|
||||||
Release process
|
|
||||||
---------------
|
|
||||||
|
|
||||||
First: bump version numbers in ``common.mk``, ``CMakeLists.txt``,
|
First: bump version numbers in ``common.mk``, ``CMakeLists.txt``,
|
||||||
``javascript/package.json``, ``python/olm/__version__.py``, ``OLMKit.podspec``,
|
``javascript/package.json``, ``python/olm/__version__.py``, ``OLMKit.podspec``,
|
||||||
|
@ -113,34 +108,32 @@ git.
|
||||||
It's probably sensible to do the above on a release branch (``release-vx.y.z``
|
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.
|
by convention), and merge back to master once the release is complete.
|
||||||
|
|
||||||
.. code:: bash
|
```bash
|
||||||
|
make clean
|
||||||
|
|
||||||
make clean
|
# build and test C library
|
||||||
|
make test
|
||||||
|
|
||||||
# build and test C library
|
# build and test JS wrapper
|
||||||
make test
|
make js
|
||||||
|
(cd javascript && npm run test)
|
||||||
|
npm pack javascript
|
||||||
|
|
||||||
# build and test JS wrapper
|
VERSION=x.y.z
|
||||||
make js
|
scp olm-$VERSION.tgz packages@ares.matrix.org:packages/npm/olm/
|
||||||
(cd javascript && npm run test)
|
git tag $VERSION -s
|
||||||
npm pack javascript
|
git push --tags
|
||||||
|
|
||||||
VERSION=x.y.z
|
# OLMKit CocoaPod release
|
||||||
scp olm-$VERSION.tgz packages@ares.matrix.org:packages/npm/olm/
|
# Make sure the version OLMKit.podspec is the same as the git tag
|
||||||
git tag $VERSION -s
|
# (this must be checked before git tagging)
|
||||||
git push --tags
|
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
|
||||||
|
```
|
||||||
|
|
||||||
# OLMKit CocoaPod release
|
## Design
|
||||||
# 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
|
|
||||||
|
|
||||||
|
|
||||||
Design
|
|
||||||
------
|
|
||||||
|
|
||||||
Olm is designed to be easy port to different platforms and to be easy
|
Olm is designed to be easy port to different platforms and to be easy
|
||||||
to write bindings for.
|
to write bindings for.
|
||||||
|
@ -150,46 +143,40 @@ 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
|
advantage, and new functionality is being added in C, with C++ parts being
|
||||||
rewritten as the need ariases.
|
rewritten as the need ariases.
|
||||||
|
|
||||||
Error Handling
|
### Error Handling
|
||||||
~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
All C functions in the API for olm return ``olm_error()`` on error.
|
All C functions in the API for olm return ``olm_error()`` on error.
|
||||||
This makes it easy to check for error conditions within the language bindings.
|
This makes it easy to check for error conditions within the language bindings.
|
||||||
|
|
||||||
Random Numbers
|
### Random Numbers
|
||||||
~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Olm doesn't generate random numbers itself. Instead the caller must
|
Olm doesn't generate random numbers itself. Instead the caller must
|
||||||
provide the random data. This makes it easier to port the library to different
|
provide the random data. This makes it easier to port the library to different
|
||||||
platforms since the caller can use whatever cryptographic random number
|
platforms since the caller can use whatever cryptographic random number
|
||||||
generator their platform provides.
|
generator their platform provides.
|
||||||
|
|
||||||
Memory
|
### Memory
|
||||||
~~~~~~
|
|
||||||
|
|
||||||
Olm avoids calling malloc or allocating memory on the heap itself.
|
Olm avoids calling malloc or allocating memory on the heap itself.
|
||||||
Instead the library calculates how much memory will be needed to hold the
|
Instead the library calculates how much memory will be needed to hold the
|
||||||
output and the caller supplies a buffer of the appropriate size.
|
output and the caller supplies a buffer of the appropriate size.
|
||||||
|
|
||||||
Output Encoding
|
### Output Encoding
|
||||||
~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Binary output is encoded as base64 so that languages that prefer unicode
|
Binary output is encoded as base64 so that languages that prefer unicode
|
||||||
strings will find it easier to handle the output.
|
strings will find it easier to handle the output.
|
||||||
|
|
||||||
Dependencies
|
### Dependencies
|
||||||
~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Olm uses pure C implementations of the cryptographic primitives used by
|
Olm uses pure C implementations of the cryptographic primitives used by
|
||||||
the ratchet. While this decreases the performance it makes it much easier
|
the ratchet. While this decreases the performance it makes it much easier
|
||||||
to compile the library for different architectures.
|
to compile the library for different architectures.
|
||||||
|
|
||||||
Contributing
|
## Contributing
|
||||||
------------
|
|
||||||
Please see `<CONTRIBUTING.rst>`_ when making contributions to the library.
|
|
||||||
|
|
||||||
Security assessment
|
Please see [CONTRIBUTING.md](CONTRIBUTING.md) when making contributions to the library.
|
||||||
-------------------
|
|
||||||
|
## Security assessment
|
||||||
|
|
||||||
Olm 1.3.0 was independently assessed by NCC Group's Cryptography Services
|
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
|
Practive in September 2016 to check for security issues: you can read all
|
||||||
|
@ -197,18 +184,16 @@ about it at
|
||||||
https://www.nccgroup.trust/us/our-research/matrix-olm-cryptographic-review/
|
https://www.nccgroup.trust/us/our-research/matrix-olm-cryptographic-review/
|
||||||
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/
|
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/
|
||||||
|
|
||||||
Bug reports
|
## Bug reports
|
||||||
-----------
|
|
||||||
Please file bug reports at https://github.com/matrix-org/olm/issues
|
Please file bug reports at https://github.com/matrix-org/olm/issues
|
||||||
|
|
||||||
What's an olm?
|
## What's an olm?
|
||||||
--------------
|
|
||||||
|
|
||||||
It's a really cool species of European troglodytic salamander.
|
It's a really cool species of European troglodytic salamander.
|
||||||
http://www.postojnska-jama.eu/en/come-and-visit-us/vivarium-proteus/
|
http://www.postojnska-jama.eu/en/come-and-visit-us/vivarium-proteus/
|
||||||
|
|
||||||
Legal Notice
|
## Legal Notice
|
||||||
------------
|
|
||||||
|
|
||||||
The software may be subject to the U.S. export control laws and regulations
|
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
|
and by downloading the software the user certifies that he/she/it is
|
Loading…
Reference in a new issue