python3-olm 3.2.18__cp314-cp314-win_amd64.whl

olm/__init__.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+# libolm python bindings
+# Copyright © 2015-2017 OpenMarket Ltd
+# Copyright © 2018 Damir Jelić <poljar@termina.org.uk>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Olm Python bindings
+~~~~~~~~~~~~~~~~~~~~~
+|  This package implements python bindings for the libolm C library.
+|  © Copyright 2015-2017 by OpenMarket Ltd
+|  © Copyright 2018 by Damir Jelić
+"""
+from .utility import ed25519_verify, OlmVerifyError, OlmHashError, sha256
+from .account import Account, OlmAccountError
+from .session import (
+    Session,
+    InboundSession,
+    OutboundSession,
+    OlmSessionError,
+    OlmMessage,
+    OlmPreKeyMessage
+)
+from .group_session import (
+    InboundGroupSession,
+    OutboundGroupSession,
+    OlmGroupSessionError
+)
+from .pk import (
+    PkMessage,
+    PkEncryption,
+    PkDecryption,
+    PkSigning,
+    PkEncryptionError,
+    PkDecryptionError,
+    PkSigningError
+)
+from .sas import Sas, OlmSasError

olm/_compat.py

@@ -0,0 +1,67 @@
+# -*- coding: utf-8 -*-
+# libolm python bindings
+# Copyright © 2015-2017 OpenMarket Ltd
+# Copyright © 2018 Damir Jelić <poljar@termina.org.uk>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from builtins import bytes, str
+from typing import AnyStr
+
+try:
+    import secrets
+    URANDOM = secrets.token_bytes  # pragma: no cover
+except ImportError:  # pragma: no cover
+    from os import urandom
+    URANDOM = urandom  # type: ignore
+
+
+def to_bytearray(string):
+    # type: (AnyStr) -> bytes
+    if isinstance(string, bytes):
+        return bytearray(string)
+    elif isinstance(string, str):
+        return bytearray(string, "utf-8")
+
+    raise TypeError("Invalid type {}".format(type(string)))
+
+
+def to_bytes(string):
+    # type: (AnyStr) -> bytes
+    if isinstance(string, bytes):
+        return string
+    elif isinstance(string, str):
+        return bytes(string, "utf-8")
+
+    raise TypeError("Invalid type {}".format(type(string)))
+
+
+def to_unicode_str(byte_string, errors="replace"):
+    """Turn a byte string into a unicode string.
+
+    Should be used everywhere where the input byte string might not be trusted
+    and may contain invalid unicode values.
+
+    Args:
+        byte_string (bytes): The bytestring that will be converted to a native
+            string.
+        errors (str, optional): The error handling scheme that should be used
+            to handle unicode decode errors. Can be one of "strict" (raise an
+            UnicodeDecodeError exception, "ignore" (remove the offending
+            characters), "replace" (replace the offending character with
+            U+FFFD), "xmlcharrefreplace" as well as any other name registered
+            with codecs.register_error that can handle UnicodeEncodeErrors.
+
+    Returns the decoded native string.
+    """
+    return byte_string.decode(encoding="utf-8", errors=errors)

olm/_finalize.py

@@ -0,0 +1,64 @@
+# The MIT License (MIT)
+# Copyright (c) 2010 Benjamin Peterson <benjamin@python.org>
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+# OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+# OR OTHER DEALINGS IN THE SOFTWARE.
+
+"""Finalization with weakrefs
+
+This is designed for avoiding __del__.
+"""
+
+import sys
+import traceback
+import weakref
+
+__author__ = "Benjamin Peterson <benjamin@python.org>"
+
+
+class OwnerRef(weakref.ref):
+    """A simple weakref.ref subclass, so attributes can be added."""
+    pass
+
+
+def _run_finalizer(ref):
+    """Internal weakref callback to run finalizers"""
+    del _finalize_refs[id(ref)]
+    finalizer = ref.finalizer
+    item = ref.item
+    try:
+        finalizer(item)
+    except Exception:  # pragma: no cover
+        print("Exception running {}:".format(finalizer), file=sys.stderr)
+        traceback.print_exc()
+
+
+_finalize_refs = {}
+
+
+def track_for_finalization(owner, item, finalizer):
+    """Register an object for finalization.
+
+    ``owner`` is the the object which is responsible for ``item``.
+    ``finalizer`` will be called with ``item`` as its only argument when
+    ``owner`` is destroyed by the garbage collector.
+    """
+    ref = OwnerRef(owner, _run_finalizer)
+    ref.item = item
+    ref.finalizer = finalizer
+    _finalize_refs[id(ref)] = ref

olm/account.py

@@ -0,0 +1,321 @@
+# -*- coding: utf-8 -*-
+# libolm python bindings
+# Copyright © 2015-2017 OpenMarket Ltd
+# Copyright © 2018 Damir Jelić <poljar@termina.org.uk>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""libolm Account module.
+
+This module contains the account part of the Olm library. It contains a single
+Account class which handles the creation of new accounts as well as the storing
+and restoring of them.
+
+Examples:
+    >>> acc = Account()
+    >>> account.identity_keys()
+    >>> account.generate_one_time_keys(1)
+
+"""
+
+import json
+# pylint: disable=redefined-builtin,unused-import
+from builtins import bytes, super
+from typing import AnyStr, Dict, Optional, Type
+
+# pylint: disable=no-name-in-module
+from _libolm import ffi, lib  # type: ignore
+
+from ._compat import URANDOM, to_bytearray
+from ._finalize import track_for_finalization
+
+# This is imported only for type checking purposes
+if False:
+    from .session import Session  # pragma: no cover
+
+
+def _clear_account(account):
+    # type: (ffi.cdata) -> None
+    lib.olm_clear_account(account)
+
+
+class OlmAccountError(Exception):
+    """libolm Account error exception."""
+
+
+class Account(object):
+    """libolm Account class."""
+
+    def __new__(cls):
+        # type: (Type[Account]) -> Account
+        obj = super().__new__(cls)
+        obj._buf = ffi.new("char[]", lib.olm_account_size())
+        obj._account = lib.olm_account(obj._buf)
+        track_for_finalization(obj, obj._account, _clear_account)
+        return obj
+
+    def __init__(self):
+        # type: () -> None
+        """Create a new Olm account.
+
+        Creates a new account and its matching identity key pair.
+
+        Raises OlmAccountError on failure. If there weren't enough random bytes
+        for the account creation the error message for the exception will be
+        NOT_ENOUGH_RANDOM.
+        """
+        # This is needed to silence mypy not knowing the type of _account.
+        # There has to be a better way for this.
+        if False:  # pragma: no cover
+            self._account = self._account  # type: ffi.cdata
+
+        random_length = lib.olm_create_account_random_length(self._account)
+        random = URANDOM(random_length)
+
+        self._check_error(
+            lib.olm_create_account(self._account, ffi.from_buffer(random),
+                                   random_length))
+
+
+    def _check_error(self, ret):
+        # type: (int) -> None
+        if ret != lib.olm_error():
+            return
+
+        last_error = ffi.string((lib.olm_account_last_error(self._account))).decode()
+
+        raise OlmAccountError(last_error)
+
+    def pickle(self, passphrase=""):
+        # type: (Optional[str]) -> bytes
+        """Store an Olm account.
+
+        Stores an account as a base64 string. Encrypts the account using the
+        supplied passphrase. Returns a byte object containing the base64
+        encoded string of the pickled account. Raises OlmAccountError on
+        failure.
+
+        Args:
+            passphrase(str, optional): The passphrase to be used to encrypt
+                the account.
+        """
+        byte_key = bytearray(passphrase, "utf-8") if passphrase else b""
+
+        pickle_length = lib.olm_pickle_account_length(self._account)
+        pickle_buffer = ffi.new("char[]", pickle_length)
+
+        try:
+            self._check_error(
+                lib.olm_pickle_account(self._account,
+                                       ffi.from_buffer(byte_key),
+                                       len(byte_key),
+                                       pickle_buffer,
+                                       pickle_length))
+        finally:
+            # zero out copies of the passphrase
+            for i in range(0, len(byte_key)):
+                byte_key[i] = 0
+
+        return ffi.unpack(pickle_buffer, pickle_length)
+
+    @classmethod
+    def from_pickle(cls, pickle, passphrase=""):
+        # type: (bytes, Optional[str]) -> Account
+        """Load a previously stored olm account.
+
+        Loads an account from a pickled base64-encoded string and returns an
+        Account object. Decrypts the account using the supplied passphrase.
+        Raises OlmAccountError on failure. If the passphrase doesn't match the
+        one used to encrypt the account then the error message for the
+        exception will be "BAD_ACCOUNT_KEY". If the base64 couldn't be decoded
+        then the error message will be "INVALID_BASE64".
+
+        Args:
+            pickle(bytes): Base64 encoded byte string containing the pickled
+                account
+            passphrase(str, optional): The passphrase used to encrypt the
+                account.
+        """
+        if not pickle:
+            raise ValueError("Pickle can't be empty")
+
+        byte_key = bytearray(passphrase, "utf-8") if passphrase else b""
+        # copy because unpickle will destroy the buffer
+        pickle_buffer = ffi.new("char[]", pickle)
+
+        obj = cls.__new__(cls)
+
+        try:
+            ret = lib.olm_unpickle_account(obj._account,
+                                           ffi.from_buffer(byte_key),
+                                           len(byte_key),
+                                           pickle_buffer,
+                                           len(pickle))
+            obj._check_error(ret)
+        finally:
+            for i in range(0, len(byte_key)):
+                byte_key[i] = 0
+
+        return obj
+
+    @property
+    def identity_keys(self):
+        # type: () -> Dict[str, str]
+        """dict: Public part of the identity keys of the account."""
+        out_length = lib.olm_account_identity_keys_length(self._account)
+        out_buffer = ffi.new("char[]", out_length)
+
+        self._check_error(
+            lib.olm_account_identity_keys(self._account, out_buffer,
+                                          out_length))
+        return json.loads(ffi.unpack(out_buffer, out_length).decode("utf-8"))
+
+    def sign(self, message):
+        # type: (AnyStr) -> str
+        """Signs a message with this account.
+
+        Signs a message with the private ed25519 identity key of this account.
+        Returns the signature.
+        Raises OlmAccountError on failure.
+
+        Args:
+            message(str): The message to sign.
+        """
+        bytes_message = to_bytearray(message)
+        out_length = lib.olm_account_signature_length(self._account)
+        out_buffer = ffi.new("char[]", out_length)
+
+        try:
+            self._check_error(
+                lib.olm_account_sign(self._account,
+                                     ffi.from_buffer(bytes_message),
+                                     len(bytes_message), out_buffer,
+                                     out_length))
+        finally:
+            # clear out copies of the message, which may be plaintext
+            if bytes_message is not message:
+                for i in range(0, len(bytes_message)):
+                    bytes_message[i] = 0
+
+        return ffi.unpack(out_buffer, out_length).decode()
+
+    @property
+    def max_one_time_keys(self):
+        # type: () -> int
+        """int: The maximum number of one-time keys the account can store."""
+        return lib.olm_account_max_number_of_one_time_keys(self._account)
+
+    def mark_keys_as_published(self):
+        # type: () -> None
+        """Mark the current set of one-time keys as being published."""
+        lib.olm_account_mark_keys_as_published(self._account)
+
+    def generate_one_time_keys(self, count):
+        # type: (int) -> None
+        """Generate a number of new one-time keys.
+
+        If the total number of keys stored by this account exceeds
+        max_one_time_keys() then the old keys are discarded.
+        Raises OlmAccountError on error.
+
+        Args:
+            count(int): The number of keys to generate.
+        """
+        random_length = lib.olm_account_generate_one_time_keys_random_length(
+            self._account, count)
+        random = URANDOM(random_length)
+
+        self._check_error(
+            lib.olm_account_generate_one_time_keys(
+                self._account, count, ffi.from_buffer(random), random_length))
+
+    @property
+    def one_time_keys(self):
+        # type: () -> Dict[str, Dict[str, str]]
+        """dict: The public part of the one-time keys for this account."""
+        out_length = lib.olm_account_one_time_keys_length(self._account)
+        out_buffer = ffi.new("char[]", out_length)
+
+        self._check_error(
+            lib.olm_account_one_time_keys(self._account, out_buffer,
+                                          out_length))
+
+        return json.loads(ffi.unpack(out_buffer, out_length).decode("utf-8"))
+
+    def remove_one_time_keys(self, session):
+        # type: (Session) -> None
+        """Remove used one-time keys.
+
+        Removes the one-time keys that the session used from the account.
+        Raises OlmAccountError on failure. If the account doesn't have any
+        matching one-time keys then the error message of the exception will be
+        "BAD_MESSAGE_KEY_ID".
+
+        Args:
+            session(Session): An Olm Session object that was created with this
+            account.
+        """
+        self._check_error(lib.olm_remove_one_time_keys(self._account,
+                                                       session._session))
+
+    def generate_fallback_key(self):
+        # type: () -> None
+        """Generate a new fallback key
+
+        This will overwrite the existing fallback key, make sure that you upload
+        the fallback key before rotating again. Internally there are two slots
+        for the private part of the fallback key. Rotating without uploading
+        means that we'll remove a fallback key that may be still used on the
+        server side but has been removed on our side.
+
+        When we receive pre-key messages that use such a removed fallback key we
+        won't be able to create a new Olm session.
+        """
+        random_length = lib.olm_account_generate_fallback_key_random_length(
+            self._account
+        )
+        random = URANDOM(random_length)
+
+        self._check_error(
+            lib.olm_account_generate_fallback_key(
+                self._account, ffi.from_buffer(random), random_length
+            )
+        )
+
+    def forget_old_fallback_key(self):
+        """Forget about the old fallback key.
+
+        This should be called once you are reasonably certain that you will not
+        receive any more messages that use the old fallback key (e.g. 5 minutes
+        after the new fallback key has been published).
+        """
+        lib.olm_account_forget_old_fallback_key(self._account)
+
+    @property
+    def fallback_key(self):
+        """The public part of the current fallback for this account.
+
+        The fallback key can be uploaded alongside of the one-time keys. It can
+        be used instead of a one-time key to establish a new Olm Session. The
+        fallback key comes into play if all one-time keys have been used up due
+        to the client being offline and not replenishing the pool of one-time
+        keys.
+        """
+        out_length = lib.olm_account_unpublished_fallback_key_length(self._account)
+        out_buffer = ffi.new("char[]", out_length)
+
+        ret = lib.olm_account_unpublished_fallback_key(self._account, out_buffer, out_length)
+        self._check_error(ret)
+
+        fallback_key = ffi.unpack(out_buffer, out_length)
+
+        return json.loads(fallback_key)