Package: python-olm
python-olmPython bindings for Olm.The specification of the Olm cryptographic ratchet which is used for peer to
peer sessions of this library can be foundhere.The specification of the Megolm cryptographic ratchet which is used for group
sessions of this library can be foundhere.An example of the implementation of the Olm and Megolm cryptographic protocol
can be found in the Matrix protocol for which the implementation guide can be
foundhere.The full API reference can be foundhere.Installation instructionsTo install from the source package, you will need:cmake (recommended) or GNU makea C/C++ compilerYou can then runpip install python-olm.This should work in UNIX-like environments, including macOS, and may work in
other environments too, but is known to not work yet in Windows.AccountsAccounts create and hold the central identity of the Olm protocol, they consist of a fingerprint and identity
key pair. They also produce one time keys that are used to start peer to peer
encrypted communication channels.Account CreationA new account is created with the Account class, it creates a new Olm key pair.
The public parts of the key pair are available using the identity_keys property
of the class.>>>alice=Account()>>>alice.identity_keys{'curve25519':'2PytGagXercwHjzQETLcMa3JOsaU2qkPIESaqoi59zE','ed25519':'HHpOuFYdHwoa54GxSttz9YmaTmbuVU3js92UTUjYJgM'}One Time keysOne time keys need to be generated before people can start an encrypted peer to
peer channel to an account.>>>alice.generate_one_time_keys(1)>>>alice.one_time_keys{'curve25519':{'AAAAAQ':'KiHoW6CIy905UC4V1Frmwr3VW8bTWkBL4uWtWFFllxM'}}After the one time keys are published they should be marked as such so they
aren't reused.>>>alice.mark_keys_as_published()>>>alice.one_time_keys{'curve25519':{}}PicklingAccounts should be stored for later reuse, storing an account is done with the
pickle method while the restoring step is done with the from_pickle class
method.>>>pickle=alice.pickle()>>>restored=Account.from_pickle(pickle)SessionsSessions are used to create an encrypted peer to peer communication channel
between two accounts.Session Creation>>>alice=Account()>>>bob=Account()>>>bob.generate_one_time_keys(1)>>>id_key=bob.identity_keys["curve25519"]>>>one_time=list(bob.one_time_keys["curve25519"].values())[0]>>>alice_session=OutboundSession(alice,id_key,one_time)EncryptionAfter an outbound session is created an encrypted message can be exchanged:>>>message=alice_session.encrypt("It's a secret to everybody")>>>message.ciphertext'AwogkL7RoakT9gnjcZMra+y39WXKRmnxBPEaEp6OSueIA0cSIJxGpBoP8YZ+CGweXQ10LujbXMgK88xG/JZMQJ5ulK9ZGiC8TYrezNYr3qyIBLlecXr/9wnegvJaSFDmWDVOcf4XfyI/AwogqIZfAklRXGC5bZJcZxVxQGgJ8Dz4OQII8k0Dp8msUXwQACIQvagY1dO55Qvnk5PZ2GF+wdKnvj6Zxl2g'>>>message.message_type0After the message is transfered, bob can create an InboundSession to decrypt the
message.>>>bob_session=InboundSession(bob,message)>>>bob_session.decrypt(message)"It's a secret to everybody"PicklingSessions like accounts can be stored for later use the API is the same as for
accounts.>>>pickle=session.pickle()>>>restored=Session.from_pickle(pickle)Group SessionsGroup Sessions are used to create a one-to-many encrypted communication channel.
The group session key needs to be shared with all participants that should be able
to decrypt the group messages. Another thing to notice is that, since the group
session key is ratcheted every time a message is encrypted, the session key should
be shared before any messages are encrypted.Group Session CreationGroup sessions aren't bound to an account like peer-to-peer sessions so their
creation is straightforward.>>>alice_group=OutboundGroupSession()>>>bob_inbound_group=InboundGroupSession(alice_group.session_key)Group EncryptionGroup encryption is pretty simple. The important part is to share the session
key with all participants over a secure channel (e.g. peer-to-peer Olm
sessions).>>>message=alice_group.encrypt("It's a secret to everybody")>>>bob_inbound_group.decrypt(message)("It's a secret to everybody",0)PicklingPickling works the same way as for peer-to-peer Olm sessions.>>>pickle=session.pickle()>>>restored=InboundGroupSession.from_pickle(pickle)