pykeepassgate 0.0.1__py3-none-any.whl

pykeepassgate/pairing.py

@@ -0,0 +1,261 @@
+"""How a stranger becomes a client: the two connections, and the order that makes it revocable.
+
+The exchange spans two connections because the gate serves one request per connection. What carries
+it across is the challenge: the server issues one against the binding and the nonce of the hello,
+holds it in memory, and spends it when the request takes it. So a request has to name a hello that
+really happened, on a connection served with the same certificate.
+
+**The client speaks first, and checks second.** Its proof goes out before the server has done
+anything, so a captured name replayed at the gate gets no further than a refusal. Only then is the
+server's own proof checked, and that check is what tells a client with no anchor yet that it
+reached the KeePass whose operator holds the token, rather than whatever accepted the connection.
+If it does not recompute, this stops: there is nothing else to go on.
+
+**Nothing here spends the invitation.** A wrong proof, a refused dialog, an unanswered one: the
+gate decides what each costs, and this reports it rather than guessing. A refusal spends the
+invitation; a timeout does not.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any
+
+from . import proofs, sni, transport
+from . import token as token_text
+from .errors import (
+    DatabaseLocked,
+    GateBusy,
+    PairingError,
+    PairingRefused,
+    PairingUnanswered,
+    ProofRefused,
+    ProtocolError,
+    RouteRefused,
+)
+
+HELLO_PATH = "/pair/hello"
+REQUEST_PATH = "/pair/request"
+
+#: What `AuthorityIssuer.IsUsableSubjectName` allows a client to be called, and
+#: `IsUsableProfileName` a profile: 1 to 64 characters out of these, and for a subject no
+#: leading or trailing space. Mirrored here rather than discovered by asking, because the gate
+#: takes the challenge before it validates, so a name it will not have costs the exchange as
+#: well as the round trip. It is also what makes `proofs.asked` unambiguous: neither of its
+#: separators can appear inside a part.
+SUBJECT_CHARACTERS = frozenset("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._ -")
+PROFILE_CHARACTERS = frozenset("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-")
+NAME_LENGTH = 64
+
+
+@dataclass(frozen=True)
+class Exchange:
+    """What a hello leaves behind for the request that follows it.
+
+    The binding and the nonce are the hello's, not the request's: the challenge was issued against
+    those, and the gate compares them. Carrying the request's own would be the mistake that makes a
+    request fail to follow its own hello.
+    """
+
+    challenge: bytes
+    binding: bytes
+    nonce: bytes
+
+
+class Pairing:
+    """One invitation, used once.
+
+    **A lost invitation is not a refusal.** An expired or already-spent one makes the
+    name resolve to nothing, and the gate drops that connection without answering at
+    all, so it reaches a caller as `TransportError` rather than as anything in the
+    pairing family. `PAIRING.md` asks the client library to name that possibility,
+    because it is otherwise indistinguishable from nothing listening.
+
+    **A refusal from `request` spends the challenge even when it spares the
+    invitation.** Recovery is a fresh `hello`, never a second `request`.
+    """
+
+    def __init__(
+        self,
+        port: int,
+        invitation: str,
+        timeout: float = transport.PAIRING_TIMEOUT,
+        host: str = transport.LOOPBACK,
+    ) -> None:
+        """Take the port the operator gave, the token from the tab, and where to dial.
+
+        Both connections of the exchange go to the same host, because they are two halves of one
+        conversation with one KeePass. The proofs are over the certificate the gate serves and the
+        token the operator handed out, so nothing about them depends on the address.
+        """
+        self._port = port
+        self._token = token_text.decode(invitation)
+        self._timeout = timeout
+        self._host = host
+
+    def hello(self) -> Exchange:
+        """Phase 3: prove the token, then check that the answer proves it too."""
+        name, nonce = sni.new_name(self._token)
+        context = transport.unpaired_context()
+
+        with transport.connect(
+            self._port, context, name, host=self._host, timeout=self._timeout
+        ) as connection:
+            bound = proofs.binding(connection.server_certificate)
+            offered = proofs.client(self._token, bound, nonce)
+            reply = connection.send(
+                "POST", HELLO_PATH, _json({"proof": _b64(offered)})
+            )
+
+        _refuse(reply)
+        body = reply.json()
+        challenge = _bytes(body, "challenge")
+        answered = _bytes(body, "proof")
+
+        expected = proofs.server(self._token, bound, nonce, challenge)
+        if not proofs.matches(expected, answered):
+            # Whatever answered is not holding this token. A client with no anchor has nothing else
+            # to check, so this is where it stops rather than where it warns.
+            raise ProofRefused("the gate's proof did not verify, so this is not the right KeePass")
+
+        return Exchange(challenge=challenge, binding=bound, nonce=nonce)
+
+    def request(self, exchange: Exchange, name: str, profiles: list[str]) -> dict[str, Any]:
+        """Phases 4 and 5: ask, wait for the operator, and take the bundle if there is one.
+
+        The profiles asked for are a ceiling rather than a grant. The operator can take any of them
+        away in the dialog, and what comes back says what was actually approved, which is not
+        always what was asked for.
+        """
+        _usable(name, profiles)
+
+        server_name, _ = sni.new_name(self._token)
+        context = transport.unpaired_context()
+
+        proof = proofs.request(
+            self._token,
+            exchange.binding,
+            exchange.nonce,
+            exchange.challenge,
+            proofs.asked(name, profiles),
+        )
+
+        body = _json({"name": name, "profiles": profiles, "proof": _b64(proof)})
+
+        with transport.connect(
+            self._port, context, server_name, host=self._host, timeout=self._timeout
+        ) as connection:
+            # The hello's proof was over the certificate the *hello* was served with,
+            # and this is a different connection: an unpaired client has no anchor, so
+            # without this it would take its own key, its trust anchor and the gate
+            # key from whatever is answering the port now. The gate makes the mirror
+            # comparison and answers `409 no exchange` (`PairingHandler.Request`);
+            # this is the half that protects the client, which is the party being
+            # handed something to trust.
+            if not proofs.matches(
+                proofs.binding(connection.server_certificate), exchange.binding
+            ):
+                raise ProofRefused(
+                    "the request reached a different certificate from its own hello"
+                )
+
+            reply = connection.send("POST", REQUEST_PATH, body)
+
+        _refuse(reply)
+        return reply.json()
+
+
+def _usable(name: str, profiles: Iterable[str]) -> None:
+    """Refuse what the gate would refuse, without spending a connection to be told.
+
+    `PairingHandler.Request` checks the name and the profiles before it takes the challenge, so
+    `400 name` and `400 profile` cost nothing on the gate's side: the exchange survives, and the
+    same hello can be followed by a corrected request. What this saves is the round trip and a
+    message that names the rule that was broken rather than the field it was broken in.
+    """
+    if not 0 < len(name) <= NAME_LENGTH or not SUBJECT_CHARACTERS.issuperset(name):
+        raise PairingError(f"that is not a name this database will issue to: {name!r}")
+
+    if name.startswith(" ") or name.endswith(" "):
+        # Measured on the plugin's side: `X500DistinguishedName` strips the space either end,
+        # so two names that differ only there become one identity in a record and in a log.
+        raise PairingError("a name cannot begin or end with a space")
+
+    for profile in profiles:
+        if not 0 < len(profile) <= NAME_LENGTH or not PROFILE_CHARACTERS.issuperset(profile):
+            raise PairingError(f"that is not a profile name: {profile!r}")
+
+        if profile.lower() == "default":
+            raise PairingError("`default` is the rule that applies when none is named")
+
+
+def _refuse(reply: transport.Response) -> None:
+    """Turn what the gate said into what a caller can act on.
+
+    Each of these is a different thing to do next, which is why they are different exceptions: wait
+    and retry, ask the operator to look at the screen, or stop and get a new invitation.
+    """
+    if reply.status == 200:
+        return
+
+    error = reply.error()
+
+    if reply.status == 503 and error == "locked":
+        raise DatabaseLocked("the database is locked, so pairing has nothing to issue from")
+
+    if reply.status == 503:
+        # The invitation survives, because the gate takes the challenge before it reaches
+        # the check that answers this and burns the invitation nowhere on this path. The
+        # challenge does not survive, so retrying this half alone earns `409 no exchange`.
+        # What can be tried again is the whole pairing, which is what `api.pair` is.
+        raise GateBusy(
+            "the gate cannot write a record right now, most likely because a group "
+            "dialog is open. The invitation is still good, but this exchange is not: "
+            "say hello again."
+        )
+
+    if reply.status == 504:
+        raise PairingUnanswered("nobody answered the dialog, and the invitation is not spent")
+
+    if reply.status == 403:
+        raise PairingRefused("the operator refused, and the invitation is spent")
+
+    if reply.status == 401 and error == "proof":
+        raise ProofRefused("the gate refused the proof, so that is not the token it is holding")
+
+    if reply.status == 404:
+        # A path under `/pair/` that is neither hello nor request. Not what a connection
+        # that lost its invitation gets: that name resolves to nothing and the gate drops
+        # the connection without a word, so it arrives here as a `TransportError`.
+        raise PairingError(
+            "the gate has no such pairing route, so these two halves disagree about the wire"
+        )
+
+    if reply.status == 409:
+        raise PairingError(
+            "the invitation is gone: it expired, it was spent, or this did not follow its own hello"
+        )
+
+    raise RouteRefused(reply.status, error)
+
+
+def _bytes(body: dict[str, Any], key: str) -> bytes:
+    value = body.get(key)
+    if not isinstance(value, str):
+        raise ProtocolError(f"the gate's answer is missing {key}")
+
+    try:
+        return base64.b64decode(value, validate=True)
+    except ValueError as error:
+        raise ProtocolError(f"the gate's {key} is not base64") from error
+
+
+def _b64(value: bytes) -> str:
+    return base64.b64encode(value).decode("ascii")
+
+
+def _json(body: dict[str, Any]) -> str:
+    return json.dumps(body, separators=(",", ":"))

pykeepassgate/proofs.py

@@ -0,0 +1,89 @@
+"""The proofs the two sides exchange before anybody is asked to approve anything.
+
+Three values, all ``HMAC-SHA256`` under the invitation token, each over a different label so that no
+proof can ever be replayed as another.
+
+**The binding is RFC 5929 ``tls-server-end-point``**: ``SHA-256`` over the DER of the certificate
+the server is actually serving with. It needs no TLS interface on either side, which is what makes
+it usable here: the server knows the certificate it chose, and the client has just been sent it.
+``SHA-256`` is not negotiated, because this authority signs with ``ecdsa-with-SHA256`` and nothing
+else. https://www.rfc-editor.org/rfc/rfc5929#section-4
+
+What each one is for:
+
+- **The client speaks first.** An impostor learns nothing and does no work until the caller has
+  shown it holds the token, so a captured name replayed at the gate dies at the first route rather
+  than in front of the operator.
+- **The server answers.** An unpaired client has no anchor yet and would otherwise accept whatever
+  certificate arrived. Because the binding hashes the certificate in use, a machine in the middle
+  can only produce a proof over its own certificate, which recomputes to something else here.
+- **The request is proved too.** ``tls-server-end-point`` is a constant for the life of a
+  certificate, so the freshness comes from the nonce the client chose and the challenge the server
+  chose, and the request carries the name and profiles being asked for, so what the operator is
+  shown is what was signed for.
+"""
+
+from __future__ import annotations
+
+import hmac
+from collections.abc import Iterable, Sequence
+from hashlib import sha256
+
+CLIENT_LABEL = b"kpg-client-proof"
+SERVER_LABEL = b"kpg-server-proof"
+REQUEST_LABEL = b"kpg-request-proof"
+
+#: ``HMAC-SHA256`` output, so every proof is this long.
+LENGTH = 32
+
+
+def binding(server_certificate_der: bytes) -> bytes:
+    """RFC 5929 ``tls-server-end-point`` over the certificate the connection is served with."""
+    return sha256(server_certificate_der).digest()
+
+
+def client(token: bytes, bound: bytes, nonce: bytes) -> bytes:
+    """What the client sends first, over the certificate it was given and the name it chose."""
+    return _compute(token, CLIENT_LABEL, [bound, nonce])
+
+
+def server(token: bytes, bound: bytes, nonce: bytes, challenge: bytes) -> bytes:
+    """What the server answers with, and what tells a client with no anchor who it reached."""
+    return _compute(token, SERVER_LABEL, [bound, nonce, challenge])
+
+
+def request(
+    token: bytes, bound: bytes, nonce: bytes, challenge: bytes, asked_for: bytes
+) -> bytes:
+    """What commits the request to the name and the profiles it asks for."""
+    return _compute(token, REQUEST_LABEL, [bound, nonce, challenge, asked_for])
+
+
+def asked(name: str, profiles: Iterable[str]) -> bytes:
+    """What a pairing request commits to: the name asked for, and the profiles, in order.
+
+    Both sides build this from the same values, so a request altered on the way no longer proves
+    itself, and the operator is shown what was signed for rather than what arrived.
+    """
+    return f"{name}\n{','.join(profiles)}".encode()
+
+
+def matches(expected: bytes, offered: bytes) -> bool:
+    """Compare two proofs in a time that does not depend on where they first differ."""
+    return hmac.compare_digest(expected, offered)
+
+
+def _compute(token: bytes, label: bytes, parts: Sequence[bytes]) -> bytes:
+    """Every part length prefixed, so no two different sets of parts produce the same bytes.
+
+    Without the prefix a name and a profile list could be shuffled across the boundary between them
+    and still verify.
+    """
+    buffer = bytearray(label)
+    buffer.append(0)
+
+    for part in parts:
+        buffer += len(part).to_bytes(4, "big")
+        buffer += part
+
+    return hmac.new(token, bytes(buffer), sha256).digest()

pykeepassgate/sni.py

@@ -0,0 +1,63 @@
+"""The name a client puts in its ClientHello.
+
+It is how a connection says which database it is for without naming it.
+
+``hex(nonce) "." hex(HMAC-SHA256(key, nonce)[0..16]) ".kpg"``, rebuilt for every connection. Two
+labels because 64 hex characters exceed the 63-octet limit on one, which is RFC 1035 section 2.3.4.
+https://www.rfc-editor.org/rfc/rfc1035#section-2.3.4
+
+The key is the gate key once a client is paired, and the invitation token while it is pairing. They
+are the same length for exactly that reason, so one construction covers both.
+
+Two honest limits, carried over from the plugin's own account of it. The tag is replayable, because
+the nonce is the client's and the server keeps no record of which have been used, so this stops
+blind probing rather than somebody who captured a connection. And the name travels in the clear, so
+an observer learns that some database is being addressed.
+"""
+
+from __future__ import annotations
+
+import hmac
+import secrets
+from hashlib import sha256
+
+#: The last label. Not a real top level domain and never resolved: nothing looks this name up,
+#: because the client is told where to connect and the name only says which database it means once
+#: it is there.
+SUFFIX = "kpg"
+
+#: Sixteen bytes, so the label is 32 hex characters and fits what a DNS label allows.
+NONCE_LENGTH = 16
+
+#: Thirty-two, which is what `CA.md` 204 specifies and what `AuthorityMaterial.SniKeyLength`
+#: refuses anything else against. The invitation token is the same length, which is what lets one
+#: construction cover both.
+KEY_LENGTH = 32
+
+#: The first sixteen bytes of the HMAC, for the same reason. Truncating an HMAC is what RFC 2104
+#: section 5 describes, and 128 bits is far more than a value an attacker gets one guess at needs.
+#: https://www.rfc-editor.org/rfc/rfc2104#section-5
+TAG_LENGTH = 16
+
+
+def tag(key: bytes, nonce: bytes) -> bytes:
+    """The tag for a nonce under a key, truncated as the name requires."""
+    return hmac.new(key, nonce, sha256).digest()[:TAG_LENGTH]
+
+
+def name_for(key: bytes, nonce: bytes) -> str:
+    """The name for a nonce that has already been chosen."""
+    if len(nonce) != NONCE_LENGTH:
+        raise ValueError(f"a nonce is {NONCE_LENGTH} bytes, not {len(nonce)}")
+
+    return f"{nonce.hex()}.{tag(key, nonce).hex()}.{SUFFIX}"
+
+
+def new_name(key: bytes) -> tuple[str, bytes]:
+    """A fresh name for one connection, and the nonce it was built from.
+
+    The nonce is returned because the proofs are computed over it: the client picks it, so it is
+    the client's half of the freshness in an exchange where the binding is a constant.
+    """
+    nonce = secrets.token_bytes(NONCE_LENGTH)
+    return name_for(key, nonce), nonce

pykeepassgate/token.py

@@ -0,0 +1,62 @@
+"""The secret an operator hands to an invitee, and how it is written down.
+
+Thirty-two bytes, because the same value is used as a gate key and a gate key is thirty-two bytes.
+It is written as base64url without padding, so it survives being pasted into a URL, a shell, a
+configuration file or a chat window without anything quoting it. That alphabet is RFC 4648
+section 5, and the padding it omits is section 3.2. https://www.rfc-editor.org/rfc/rfc4648#section-5
+
+The plugin only ever encodes and this only ever decodes, so `encode` exists here to be tested
+against `decode` rather than because a client needs it.
+"""
+
+from __future__ import annotations
+
+import base64
+
+from .errors import MalformedToken
+
+#: The same length as a gate key, because a token is used as one.
+LENGTH = 32
+
+#: Thirty-two bytes in base64url is forty-three characters, with no padding.
+TEXT_LENGTH = 43
+
+_ALPHABET = frozenset("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_")
+
+
+def encode(token: bytes) -> str:
+    """Write a token the way the tab writes it."""
+    if len(token) != LENGTH:
+        raise MalformedToken(f"a token is {LENGTH} bytes, not {len(token)}")
+
+    return base64.urlsafe_b64encode(token).decode("ascii").rstrip("=")
+
+
+def decode(text: str) -> bytes:
+    """Read one back.
+
+    Refuses anything that is not exactly a token: the wrong length, a character outside the
+    alphabet, or padding, which the plugin never writes. Fail closed, in the same way and for the
+    same reason the plugin's own decoder does.
+    """
+    if len(text) != TEXT_LENGTH:
+        raise MalformedToken(
+            f"a token is {TEXT_LENGTH} characters, not {len(text)}"
+        )
+
+    if not _ALPHABET.issuperset(text):
+        raise MalformedToken("a token is base64url, and this is not")
+
+    # The padding the encoder omits, put back so the standard library will read it. 43 characters
+    # is 32 bytes and one short of a whole block, so one "=" is what is missing; a second is
+    # harmless and saves counting.
+    token = base64.urlsafe_b64decode(text + "==")
+
+    # 43 characters carry 258 bits for a 256 bit token, so the last one has two bits the token
+    # does not use and the decoder does not look at: four spellings decode to the same bytes.
+    # Re-encoding refuses the three the plugin would never write. There is no length check after
+    # this, because 43 characters of the alphabet are 32 bytes and can be nothing else.
+    if encode(token) != text:
+        raise MalformedToken("a token has one spelling, and this is not it")
+
+    return token