{"id":13557560,"url":"https://github.com/poljar/python-olm","last_synced_at":"2025-04-03T11:32:30.498Z","repository":{"id":57457313,"uuid":"123592029","full_name":"poljar/python-olm","owner":"poljar","description":"python bindings for the Olm C library","archived":true,"fork":false,"pushed_at":"2019-06-27T07:30:48.000Z","size":350,"stargazers_count":13,"open_issues_count":0,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-19T15:17:07.797Z","etag":null,"topics":["cryptography","encryption","matrix","olm","python-bindings"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/poljar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-03-02T14:53:57.000Z","updated_at":"2025-02-14T17:34:21.000Z","dependencies_parsed_at":"2022-09-06T02:01:08.948Z","dependency_job_id":null,"html_url":"https://github.com/poljar/python-olm","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poljar%2Fpython-olm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poljar%2Fpython-olm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poljar%2Fpython-olm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poljar%2Fpython-olm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/poljar","download_url":"https://codeload.github.com/poljar/python-olm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246993265,"owners_count":20865972,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cryptography","encryption","matrix","olm","python-bindings"],"created_at":"2024-08-01T12:04:25.213Z","updated_at":"2025-04-03T11:32:25.483Z","avatar_url":"https://github.com/poljar.png","language":"Python","funding_links":[],"categories":["Python","others"],"sub_categories":[],"readme":"python-olm\n==========\n\n[![Travis Build Status](https://travis-ci.org/poljar/python-olm.svg?branch=master)](https://travis-ci.org/poljar/python-olm)\n[![Codecov Coverage Status](https://codecov.io/gh/poljar/python-olm/branch/master/graph/badge.svg)](https://codecov.io/gh/poljar/python-olm)\n\n## This has been merged into the main [Olm repo](https://gitlab.matrix.org/matrix-org/olm).\n\nPython bindings for Olm.\n\nThis is a fork of the official [python bindings][2] for the Olm C library found [here][1].\nThe bindings were rewritten using [CFFI for python][3].\n\nThe specification of the Olm cryptographic ratchet which is used for peer to\npeer sessions of this library can be found [here][4].\n\nThe specification of the Megolm cryptographic ratchet which is used for group\nsessions of this library can be found [here][5].\n\nAn example of the implementation of the Olm and Megolm cryptographic protocol\ncan be found in the Matrix protocol for which the implementation guide can be\nfound [here][6].\n\nThe full API reference can be found [here][7].\n\n# Accounts\n\nAccounts create and hold the central identity of the Olm protocol, they consist of a fingerprint and identity\nkey pair. They also produce one time keys that are used to start peer to peer\nencrypted communication channels.\n\n## Account Creation\n\nA new account is created with the Account class, it creates a new Olm key pair.\nThe public parts of the key pair are available using the identity_keys property\nof the class.\n\n```python\n\u003e\u003e\u003e alice = Account()\n\u003e\u003e\u003e alice.identity_keys\n{'curve25519': '2PytGagXercwHjzQETLcMa3JOsaU2qkPIESaqoi59zE',\n 'ed25519': 'HHpOuFYdHwoa54GxSttz9YmaTmbuVU3js92UTUjYJgM'}\n```\n\n\n## One Time keys\n\nOne time keys need to be generated before people can start an encrypted peer to\npeer channel to an account.\n\n```python\n\u003e\u003e\u003e alice.generate_one_time_keys(1)\n\u003e\u003e\u003e alice.one_time_keys\n{'curve25519': {'AAAAAQ': 'KiHoW6CIy905UC4V1Frmwr3VW8bTWkBL4uWtWFFllxM'}}\n```\n\nAfter the one time keys are published they should be marked as such so they\naren't reused.\n\n```python\n\u003e\u003e\u003e alice.mark_keys_as_published()\n\u003e\u003e\u003e alice.one_time_keys\n{'curve25519': {}}\n```\n\n## Pickling\n\nAccounts should be stored for later reuse, storing an account is done with the\npickle method while the restoring step is done with the from_pickle class\nmethod.\n\n```python\n\u003e\u003e\u003e pickle = alice.pickle()\n\u003e\u003e\u003e restored = Account.from_pickle(pickle)\n```\n\n# Sessions\n\nSessions are used to create an encrypted peer to peer communication channel\nbetween two accounts.\n\n## Session Creation\n```python\n\u003e\u003e\u003e alice = Account()\n\u003e\u003e\u003e bob = Account()\n\u003e\u003e\u003e bob.generate_one_time_keys(1)\n\u003e\u003e\u003e id_key = bob.identity_keys[\"curve25519\"]\n\u003e\u003e\u003e one_time = list(bob.one_time_keys[\"curve25519\"].values())[0]\n\u003e\u003e\u003e alice_session = OutboundSession(alice, id_key, one_time)\n```\n\n## Encryption\n\nAfter an outbound session is created an encrypted message can be exchanged:\n\n```python\n\u003e\u003e\u003e message = alice_session.encrypt(\"It's a secret to everybody\")\n\u003e\u003e\u003e message.ciphertext\n'AwogkL7RoakT9gnjcZMra+y39WXKRmnxBPEaEp6OSueIA0cSIJxGpBoP8YZ+CGweXQ10LujbXMgK88\nxG/JZMQJ5ulK9ZGiC8TYrezNYr3qyIBLlecXr/9wnegvJaSFDmWDVOcf4XfyI/AwogqIZfAklRXGC5b\nZJcZxVxQGgJ8Dz4OQII8k0Dp8msUXwQACIQvagY1dO55Qvnk5PZ2GF+wdKnvj6Zxl2g'\n\u003e\u003e\u003e message.message_type\n0\n```\n\nAfter the message is transfered, bob can create an InboundSession to decrypt the\nmessage.\n\n```python\n\u003e\u003e\u003e bob_session = InboundSession(bob, message)\n\u003e\u003e\u003e bob_session.decrypt(message)\n\"It's a secret to everybody\"\n```\n\n## Pickling\n\nSessions like accounts can be stored for later use the API is the same as for\naccounts.\n\n```python\n\u003e\u003e\u003e pickle = session.pickle()\n\u003e\u003e\u003e restored = Session.from_pickle(pickle)\n```\n\n# Group Sessions\n\nGroup Sessions are used to create a one-to-many encrypted communication channel.\nThe group session key needs to be shared with all participants that should be able\nto decrypt the group messages. Another thing to notice is that, since the group\nsession key is ratcheted every time a message is encrypted, the session key should\nbe shared before any messages are encrypted.\n\n## Group Session Creation\n\nGroup sessions aren't bound to an account like peer-to-peer sessions so their\ncreation is straightforward.\n\n```python\n\u003e\u003e\u003e alice_group = OutboundGroupSession()\n\u003e\u003e\u003e bob_inbound_group = InboundGroupSession(alice_group.session_key)\n```\n\n## Group Encryption\n\nGroup encryption is pretty simple. The important part is to share the session\nkey with all participants over a secure channel (e.g. peer-to-peer Olm\nsessions).\n\n```python\n\u003e\u003e\u003e message = alice_group.encrypt(\"It's a secret to everybody\")\n\u003e\u003e\u003e bob_inbound_group.decrypt(message)\n(\"It's a secret to everybody\", 0)\n```\n\n## Pickling\n\nPickling works the same way as for peer-to-peer Olm sessions.\n\n```python\n\u003e\u003e\u003e pickle = session.pickle()\n\u003e\u003e\u003e restored = InboundGroupSession.from_pickle(pickle)\n```\n[1]: https://git.matrix.org/git/olm/about/\n[2]: https://git.matrix.org/git/olm/tree/python?id=f8c61b8f8432d0b0b38d57f513c5048fb42f22ab\n[3]: https://cffi.readthedocs.io/en/latest/\n[4]: https://git.matrix.org/git/olm/about/docs/olm.rst\n[5]: https://git.matrix.org/git/olm/about/docs/megolm.rst\n[6]: https://matrix.org/docs/guides/e2e_implementation.html\n[7]: https://poljar.github.io/python-olm/html/index.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpoljar%2Fpython-olm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpoljar%2Fpython-olm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpoljar%2Fpython-olm/lists"}