shieldy-sdk 1.0.2__py3-none-win_amd64.whl

shieldy/__init__.py

@@ -0,0 +1,88 @@
+"""Shieldy Python SDK: license checks, remote variables, files and Protected Strings.
+
+One process holds one Shieldy session, because the native runtime does: the calls below are
+module-level functions on that session and are safe to make from any thread.
+
+    import shieldy
+
+    shieldy.start(shieldy.Config("<App GUID>", "1.0"), license_key)   # raises shieldy.ShieldyError
+
+    lic = shieldy.license()
+    if lic.level >= 20:
+        enable_pro_features()
+
+    url = shieldy.variable_by_id("<Lookup ID>")                       # str
+    max_users = shieldy.variable_by_id_as("<Lookup ID>", int)         # int
+    with shieldy.file_by_id("<Lookup ID>") as pak:                    # SecureBytes, wiped after
+        load(pak.view())
+    token = shieldy.protected_string("<ciphertext>")
+
+Every call raises :class:`ShieldyError` when it cannot deliver; ``exc.error`` is an
+:class:`Error` code with the same numbers as the C++ SDK's ``shieldy::Error``.
+
+The SDK is a thin client of the native runtime (``native.dll`` / ``native.so``), which does the
+integrity checks and all network traffic. What happens in which module:
+
+* ``_native``  - finding and loading the runtime
+* ``_abi``     - the ctypes mirror of the runtime's C ABI (``shieldy_api.h``)
+* ``_crypto``  - key agreement, attestation and decryption of what the runtime returns
+* ``_session`` - the process-wide session and every public call
+* ``obf``      - the ``SHIELDY_OBF`` marker and its release check
+"""
+
+from ._native import application_directory
+from ._session import (
+    checkpoint,
+    checkpoint_failed,
+    connection_state,
+    file,
+    file_by_id,
+    init,
+    is_logged_in,
+    license,
+    login,
+    protected_bytes,
+    protected_int,
+    protected_string,
+    shutdown,
+    start,
+    supports,
+    variable,
+    variable_as,
+    variable_by_id,
+    variable_by_id_as,
+)
+from .errors import Error, ShieldyError
+from .values import Config, ConnectionState, Feature, License, SecureBytes
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "Config",
+    "ConnectionState",
+    "Error",
+    "Feature",
+    "License",
+    "SecureBytes",
+    "ShieldyError",
+    "application_directory",
+    "checkpoint",
+    "checkpoint_failed",
+    "connection_state",
+    "file",
+    "file_by_id",
+    "init",
+    "is_logged_in",
+    "license",
+    "login",
+    "protected_bytes",
+    "protected_int",
+    "protected_string",
+    "shutdown",
+    "start",
+    "supports",
+    "variable",
+    "variable_as",
+    "variable_by_id",
+    "variable_by_id_as",
+]

shieldy/_abi.py

@@ -0,0 +1,120 @@
+"""ctypes mirror of ShieldyCore's public ABI, ``cpp-module/shieldy_api.h``.
+
+The runtime exports exactly one symbol, ``SC_GetApi``, which fills an ``SC_ApiV1`` table of
+function pointers. Everything else the SDK does goes through that table. The layout below must
+match the header field for field: the table is read by offset, so a reordered or missing field
+calls the wrong function.
+
+Kept free of any SDK logic so it can be diffed against the C header on its own. When the header
+gains fields, append them here in the same order (the header only ever appends after ``destroy``).
+"""
+
+from __future__ import annotations
+
+import ctypes
+from ctypes import POINTER, Structure, c_char_p, c_int32, c_int64, c_size_t, c_uint8, c_uint32, c_void_p
+
+SC_PUBLIC_KEY_SIZE = 32
+SC_API_VERSION_1 = 1
+
+# SC_Result. Only SC_OK is compared against here; the other codes are mapped onto
+# shieldy.Error, which uses the same numbers for them (see errors.py).
+SC_OK = 0
+SC_RESULT_MIN_ERROR = 1  # SC_ERROR_UNKNOWN
+SC_RESULT_MAX_ERROR = 17  # SC_ERROR_OFFLINE_UNAVAILABLE
+
+# SC_Result is a C enum: int-sized on every platform the runtime ships for.
+SC_Result = ctypes.c_int
+
+
+class SC_PublicKey(Structure):
+    _fields_ = [("bytes", c_uint8 * SC_PUBLIC_KEY_SIZE)]
+
+
+class SC_Config(Structure):
+    # The caller sets struct_size = sizeof(SC_Config) before passing it to create(). A runtime
+    # before protocol 1.12.0 compares struct_size with its own, smaller sizeof and accepts it.
+    _fields_ = [
+        ("struct_size", c_uint32),
+        ("appGuid", c_char_p),
+        ("appVersion", c_char_p),
+        ("appMode", c_int32),
+        # Appended in protocol 1.12.0.
+        ("leaseDirectory", c_char_p),
+    ]
+
+
+SC_CONNECTION_MODE_ONLINE = 0
+SC_CONNECTION_MODE_OFFLINE = 1
+
+
+class SC_ConnectionState(Structure):
+    # Protocol 1.12.0. The caller sets struct_size = sizeof(SC_ConnectionState).
+    _fields_ = [
+        ("struct_size", c_uint32),
+        ("mode", c_int32),
+        ("offline_until", c_int64),
+    ]
+
+
+class SC_Buffer(Structure):
+    # As input the caller owns `data`. As output the runtime allocates it and the caller hands it
+    # back through free_buffer(). Not NUL-terminated.
+    _fields_ = [
+        ("data", POINTER(c_uint8)),
+        ("size", c_size_t),
+    ]
+
+
+class SC_LoginRequest(Structure):
+    _fields_ = [
+        ("licenseKey", c_char_p),
+        ("sdkPublicKey", SC_PublicKey),
+    ]
+
+
+# SC_Context is opaque: the SDK only ever passes the pointer back.
+SC_ContextPtr = c_void_p
+
+# Function pointer types of the table. All of them use the platform's default C calling
+# convention (cdecl on x86), hence CFUNCTYPE rather than WINFUNCTYPE.
+CreateFn = ctypes.CFUNCTYPE(SC_Result, POINTER(SC_Config), POINTER(SC_ContextPtr))
+InitializeFn = ctypes.CFUNCTYPE(SC_Result, SC_ContextPtr)
+LoginFn = ctypes.CFUNCTYPE(SC_Result, SC_ContextPtr, POINTER(SC_LoginRequest), POINTER(SC_PublicKey))
+OpenBlackboxFn = ctypes.CFUNCTYPE(SC_Result, SC_ContextPtr, POINTER(SC_Buffer), POINTER(SC_Buffer))
+# get_license_property, get_variable, deobf_string, download_file and the *_by_id pair all share
+# this shape: (context, NUL-terminated key, out buffer).
+LookupFn = ctypes.CFUNCTYPE(SC_Result, SC_ContextPtr, c_char_p, POINTER(SC_Buffer))
+FreeBufferFn = ctypes.CFUNCTYPE(None, SC_ContextPtr, POINTER(SC_Buffer))
+DestroyFn = ctypes.CFUNCTYPE(None, SC_ContextPtr)
+ConnectionStateFn = ctypes.CFUNCTYPE(SC_Result, SC_ContextPtr, POINTER(SC_ConnectionState))
+
+
+class SC_ApiV1(Structure):
+    # Field order is the ABI. The caller sets struct_size = sizeof(SC_ApiV1) before SC_GetApi.
+    _fields_ = [
+        ("struct_size", c_uint32),
+        ("abi_version", c_uint32),
+        ("create", CreateFn),
+        ("initialize", InitializeFn),
+        ("login", LoginFn),
+        ("open_blackbox", OpenBlackboxFn),
+        ("get_license_property", LookupFn),
+        ("get_variable", LookupFn),
+        ("deobf_string", LookupFn),
+        ("download_file", LookupFn),
+        ("free_buffer", FreeBufferFn),
+        ("destroy", DestroyFn),
+        # Appended in protocol 1.6.0. A runtime older than that leaves them NULL.
+        ("get_variable_by_id", LookupFn),
+        ("download_file_by_id", LookupFn),
+        # Appended in protocol 1.12.0 (offline start). NULL on older runtimes.
+        ("get_connection_state", ConnectionStateFn),
+    ]
+
+
+# The size of SC_ApiV1 as first shipped (up to and including `destroy`). SC_GetApi accepts any
+# struct_size from this up, which is what lets a newer SDK run on an older runtime.
+SC_API_V1_BASE_SIZE = SC_ApiV1.destroy.offset + ctypes.sizeof(DestroyFn)
+
+GetApiFn = ctypes.CFUNCTYPE(SC_Result, c_uint32, POINTER(SC_ApiV1))

shieldy/_crypto.py

@@ -0,0 +1,142 @@
+"""The SDK's half of a login: key agreement, attestation and unwrapping the runtime's output.
+
+The wire format is fixed by ShieldyCore and mirrored from the C++ SDK (``src/session_crypto.cpp``):
+
+* **Key agreement.** Each login generates a fresh X25519 key pair. The SDK sends its public key in
+  ``SC_LoginRequest.sdkPublicKey``; the runtime answers with its own. Both sides compute the raw
+  X25519 shared secret and hash it with **plain SHA-256** (ShieldyCore ``crypto_ecdh.cpp``,
+  ``compute_shared_secret``). That digest is the 32-byte session key.
+* **Attestation.** Before trusting anything else, the SDK sends 16 random bytes to
+  ``open_blackbox``; the runtime must answer ``HMAC-SHA256(session_key, nonce)``. A runtime that
+  cannot is not the one that did the key agreement.
+* **Output wrapping.** Every value the runtime hands back (license fields, variables, files,
+  Protected Strings) is ``nonce(12) || tag(16) || ciphertext`` under ChaCha20-Poly1305 (IETF)
+  with the session key and no associated data. Note the tag sits *before* the ciphertext; most
+  libraries, ``cryptography`` included, expect it after, so :meth:`Session.decrypt` reorders.
+
+Memory hygiene is best effort, as it has to be in Python: the session key lives in a
+``bytearray`` that is zeroed when the session ends, and decrypted files are written straight into
+a buffer :class:`~shieldy.SecureBytes` can wipe. Copies the interpreter or OpenSSL make
+internally are out of the SDK's reach.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+from typing import Optional
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey, X25519PublicKey
+from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305
+
+from .errors import Error, ShieldyError
+from .values import SecureBytes
+
+KEY_SIZE = 32
+CHALLENGE_NONCE_SIZE = 16  # the size open_blackbox accepts
+NONCE_SIZE = 12
+TAG_SIZE = 16
+
+
+def random_bytes(size: int) -> bytes:
+    return os.urandom(size)
+
+
+def wipe(buffer: bytearray) -> None:
+    """Overwrite a mutable buffer with zeros in place."""
+    buffer[:] = bytes(len(buffer))
+
+
+class Session:
+    """One login's key material. A new :meth:`begin` drops the previous session entirely."""
+
+    def __init__(self) -> None:
+        self._private_key: Optional[X25519PrivateKey] = None
+        self._public_key = b""
+        self._session_key = bytearray()
+        self._aead: Optional[ChaCha20Poly1305] = None
+
+    def begin(self) -> bytes:
+        """Generate a fresh key pair and return the public half to send to the runtime."""
+        self.clear()
+        self._private_key = X25519PrivateKey.generate()
+        self._public_key = self._private_key.public_key().public_bytes(
+            serialization.Encoding.Raw, serialization.PublicFormat.Raw
+        )
+        return self._public_key
+
+    @property
+    def public_key(self) -> bytes:
+        return self._public_key
+
+    @property
+    def has_key(self) -> bool:
+        return self._aead is not None
+
+    def derive(self, peer_public_key: bytes) -> bool:
+        """Turn the runtime's public key into the session key. False when the exchange is invalid.
+
+        The private key is dropped either way: it is single use.
+        """
+        private_key, self._private_key = self._private_key, None
+        if private_key is None or len(peer_public_key) != KEY_SIZE:
+            return False
+        try:
+            # Raises ValueError for a low-order peer key (all-zero shared secret), which is the
+            # same input libsodium's crypto_scalarmult refuses in the C++ SDK.
+            shared = bytearray(private_key.exchange(X25519PublicKey.from_public_bytes(peer_public_key)))
+        except ValueError:
+            return False
+        self._session_key = bytearray(hashlib.sha256(shared).digest())
+        wipe(shared)
+        self._aead = ChaCha20Poly1305(bytes(self._session_key))
+        return True
+
+    def verify_challenge(self, nonce: bytes, response: bytes) -> bool:
+        """Check ``response == HMAC-SHA256(session_key, nonce)`` in constant time."""
+        if not self.has_key or len(response) != hashlib.sha256().digest_size:
+            return False
+        expected = hmac.new(bytes(self._session_key), nonce, hashlib.sha256).digest()
+        return hmac.compare_digest(expected, response)
+
+    def decrypt(self, wrapped: bytes) -> SecureBytes:
+        """Unwrap one value from the runtime into a wipeable buffer.
+
+        Raises ``ShieldyError(NOT_LOGGED_IN)`` without a session key and
+        ``ShieldyError(DECRYPT_FAILED)`` when the value is malformed or fails authentication.
+        """
+        if self._aead is None:
+            raise ShieldyError(Error.NOT_LOGGED_IN)
+        if len(wrapped) < NONCE_SIZE + TAG_SIZE:
+            raise ShieldyError(Error.DECRYPT_FAILED)
+
+        nonce = wrapped[:NONCE_SIZE]
+        tag = wrapped[NONCE_SIZE:NONCE_SIZE + TAG_SIZE]
+        ciphertext = wrapped[NONCE_SIZE + TAG_SIZE:]
+        plain = bytearray(len(ciphertext))
+        try:
+            self._decrypt_into(nonce, ciphertext + tag, plain)
+        except InvalidTag:
+            wipe(plain)
+            raise ShieldyError(Error.DECRYPT_FAILED) from None
+        return SecureBytes._adopt(plain)
+
+    def _decrypt_into(self, nonce: bytes, ciphertext_and_tag: bytes, out: bytearray) -> None:
+        assert self._aead is not None
+        decrypt_into = getattr(self._aead, "decrypt_into", None)
+        if decrypt_into is not None:
+            # cryptography >= 45: plaintext goes straight into our buffer, no immutable copy.
+            decrypt_into(nonce, ciphertext_and_tag, None, out)
+        else:
+            out[:] = self._aead.decrypt(nonce, ciphertext_and_tag, None)
+
+    def clear(self) -> None:
+        """Forget everything; the next value needs a new login."""
+        self._private_key = None
+        self._public_key = b""
+        wipe(self._session_key)
+        self._session_key = bytearray()
+        self._aead = None

shieldy/_native.py

@@ -0,0 +1,128 @@
+"""Finding and loading the native runtime.
+
+The runtime is a shared library (``native.dll`` on Windows, ``native.so`` on Linux) that your
+application ships. Which file gets loaded is a security decision, so the rules are strict:
+
+1. ``Config.native_library`` if set, else the ``SHIELDY_NATIVE_LIBRARY`` environment variable,
+   else the default file name.
+2. A relative path is resolved against :func:`application_directory`, and then against the
+   package's own directory (:func:`bundled_directories`, where a wheel that bundles the runtime
+   puts it), **never** the current working directory or ``PATH``, so a library planted where the
+   user happens to start your program from is not picked up.
+3. On Windows the library's own dependencies are searched only in its directory and System32
+   (``LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR | LOAD_LIBRARY_SEARCH_SYSTEM32``), as in the C++ SDK.
+
+A loaded runtime is never unloaded: it keeps protection threads running for the life of the
+process.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import sys
+from typing import Any, List, Optional
+
+from . import _abi
+from .errors import Error, ShieldyError
+
+ENVIRONMENT_VARIABLE = "SHIELDY_NATIVE_LIBRARY"
+
+def _default_file_name(platform: str) -> str:
+    """The runtime's file name on ``platform`` (a ``sys.platform`` value)."""
+    if platform == "win32":
+        return "native.dll"
+    if platform == "darwin":
+        return "native.dylib"
+    return "native.so"
+
+
+DEFAULT_FILE_NAME = _default_file_name(sys.platform)
+
+_LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR = 0x00000100
+_LOAD_LIBRARY_SEARCH_SYSTEM32 = 0x00000800
+
+# Loaded libraries, kept referenced so ctypes never lets go of them.
+_loaded: List[ctypes.CDLL] = []
+
+
+def application_directories() -> List[str]:
+    """The directories a relative runtime path is looked up in, in order.
+
+    * A frozen application (PyInstaller, cx_Freeze, py2exe): the directory of the executable,
+      then PyInstaller's bundle directory (``sys._MEIPASS``) when it differs, which is where a
+      one-file build unpacks ``--add-binary`` files.
+    * A script: the directory of the ``__main__`` script, i.e. the file you ran with ``python``.
+      For ``python -m package`` that is the package's directory.
+    * No main script (interactive interpreter, ``python -c``, an embedding host): none. Pass an
+      absolute path then.
+    """
+    if getattr(sys, "frozen", False):
+        directories = [os.path.dirname(os.path.abspath(sys.executable))]
+        bundle = getattr(sys, "_MEIPASS", None)
+        if bundle and os.path.abspath(bundle) not in directories:
+            directories.append(os.path.abspath(bundle))
+        return directories
+
+    main = sys.modules.get("__main__")
+    main_file = getattr(main, "__file__", None)
+    if main_file:
+        return [os.path.dirname(os.path.abspath(main_file))]
+    return []
+
+
+def application_directory() -> Optional[str]:
+    """The first of :func:`application_directories`, or ``None`` when there is none."""
+    directories = application_directories()
+    return directories[0] if directories else None
+
+
+def bundled_directories() -> List[str]:
+    """Install locations a relative runtime path falls back to, after the application directories.
+
+    The package's own directory: where a wheel that bundles the runtime (the per-platform releases
+    on PyPI) places ``native.dll`` / ``native.so`` / ``native.dylib``. This is the install location, not the current
+    working directory or ``PATH``, so it is as trustworthy as the application directory. A source
+    build with no bundled runtime simply has nothing here, and the application's own copy wins.
+    """
+    return [os.path.dirname(os.path.abspath(__file__))]
+
+
+def resolve(configured_path: str) -> Optional[str]:
+    """The absolute path that :func:`load_get_api` would load, or ``None`` when it cannot tell."""
+    path = configured_path or os.environ.get(ENVIRONMENT_VARIABLE, "") or DEFAULT_FILE_NAME
+    if os.path.isabs(path):
+        return os.path.normpath(path)
+    candidates = [
+        os.path.normpath(os.path.join(directory, path))
+        for directory in application_directories() + bundled_directories()
+    ]
+    for candidate in candidates:
+        if os.path.isfile(candidate):
+            return candidate
+    # Nothing exists yet: report the first candidate so the error names a useful place.
+    return candidates[0] if candidates else None
+
+
+def _open(path: str) -> ctypes.CDLL:
+    if sys.platform == "win32":
+        return ctypes.CDLL(path, winmode=_LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR | _LOAD_LIBRARY_SEARCH_SYSTEM32)
+    return ctypes.CDLL(path, mode=os.RTLD_NOW | os.RTLD_LOCAL)
+
+
+def load_get_api(configured_path: str) -> Any:
+    """Load the runtime and return its ``SC_GetApi`` as a callable :data:`_abi.GetApiFn`."""
+    path = resolve(configured_path)
+    if path is None or not os.path.isfile(path):
+        raise ShieldyError(Error.NATIVE_LIBRARY_NOT_FOUND)
+    try:
+        library = _open(path)
+    except OSError:
+        # Also what a library for the wrong architecture (x86 DLL in 64-bit Python) ends up as.
+        raise ShieldyError(Error.NATIVE_LIBRARY_NOT_FOUND) from None
+    try:
+        get_api = _abi.GetApiFn(("SC_GetApi", library))
+    except AttributeError:
+        raise ShieldyError(Error.NATIVE_LIBRARY_INVALID) from None
+    _loaded.append(library)
+    return get_api