ccssh 1.0.0__py3-none-any.whl

ccssh/certs.py

@@ -0,0 +1,283 @@
+"""
+ OpenSSH certificates (draft-miller-ssh-cert, *-cert-v01@openssh.com,
+ ssh-mldsa44-ed25519-cert).
+
+ Implemented: parsing, CA signatures (ed25519/mldsa/ecdsa/rsa), validity
+ periods, principals, critical options (unknown ones REJECT the cert),
+ @cert-authority lines from known_hosts.
+ Not implemented: verify-required touch checks (such certs are rejected),
+ source-address enforcement (a server-side concern for user certs).
+"""
+from __future__ import annotations
+import base64
+import fnmatch
+import os
+import time
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+
+from ccssh import hostkeys as HK
+from ccssh import mldsa as ML
+from ccssh import wire as W
+
+CERT_TYPE_USER = 1
+CERT_TYPE_HOST = 2
+
+# Known user critical options (draft section 2.3). Unknown ones REJECT the cert.
+KNOWN_CRITICAL = {"force-command", "source-address", "verify-required"}
+
+
+class CertError(ValueError):
+    pass
+
+
+def _parse_section(raw: bytes) -> dict[str, bytes]:
+    """A critical-options/extensions section: sequence of {string key, string value}."""
+    r = W.Reader(raw)
+    out: dict[str, bytes] = {}
+    while r.rest():
+        k = r.string().decode()
+        v = r.string()
+        out[k] = v
+    return out
+
+
+def parse_cert(blob: bytes) -> dict:
+    """
+     Parse and structurally validate a certificate blob.
+
+     Raises CertError (never bare WireError/UnicodeDecodeError) so callers
+     get one clean failure type for attacker-controlled input.
+    """
+    try:
+        return _parse_cert_inner(blob)
+    except CertError:
+        raise
+    except Exception as e:
+        raise CertError(f"malformed certificate: {e}") from e
+
+
+def _parse_cert_inner(blob: bytes) -> dict:
+    r = W.Reader(blob)
+    keytype = r.string().decode()
+    if not (keytype.endswith("-cert-v01@openssh.com") or keytype.endswith("-cert")):
+        raise CertError(f"not a certificate type {keytype!r}")
+    nonce = r.string()
+    pub: dict = {}
+    if keytype.startswith("ssh-ed25519"):
+        pub = {"pub": r.string()}
+        if len(pub["pub"]) != 32:
+            raise CertError("bad ed25519 pub length")
+    elif keytype.startswith("ssh-mldsa44-ed25519"):
+        pub = {"pub": r.string()}
+        if len(pub["pub"]) != ML.PK_LEN:
+            raise CertError("bad mldsa pub length")
+    elif keytype.startswith("ecdsa-sha2-"):
+        pub = {"curve": r.string().decode(), "q": r.string()}
+    elif keytype.startswith("ssh-rsa"):
+        pub = {"e": r.mpint(), "n": r.mpint()}
+    else:
+        raise CertError(f"unsupported certificate type {keytype!r}")
+    serial = r.u64()
+    role = r.u32()
+    key_id = r.string()
+    """
+     Principals is a string CONTAINING cstrings (see sshkey_certify_custom
+     in OpenSSH sshkey.c), NOT comma-joined text as the draft suggests.
+    """
+    principals_raw = r.string()
+    principals: list[str] = []
+    if principals_raw:
+        pr = W.Reader(principals_raw)
+        while pr.rest():
+            principals.append(pr.string().decode())
+    valid_after = r.u64()
+    valid_before = r.u64()
+    crit_raw = r.string()
+    ext_raw = r.string()
+    _reserved = r.string()
+    if _reserved:
+        raise CertError("certificate reserved field must be empty")
+    sig_key = r.string()
+    sig_off = r.tell() # the signature covers everything up to this point
+    signature = r.string()
+    if r.rest():
+        raise CertError("trailing bytes in certificate")
+    return {"keytype": keytype,
+            "nonce": nonce,
+            "pub": pub,
+            "serial": serial,
+            "role": role,
+            "key_id": key_id,
+            "principals": principals,
+            "valid_after": valid_after,
+            "valid_before": valid_before,
+            "critical": _parse_section(crit_raw),
+            "extensions": _parse_section(ext_raw),
+            "sig_key": sig_key,
+            "signature": signature,
+            "signed_data": blob[:sig_off]}
+
+
+def _ca_verify_signed(signed: bytes, sig_key_blob: bytes, signature: bytes) -> bool:
+    """Verify a CA signature according to the CA key type. Never raises."""
+    r = W.Reader(sig_key_blob)
+    try:
+        ca_type = r.string().decode()
+    except Exception:
+        return False
+    if ca_type in ("ssh-ed25519",):
+        rr = W.Reader(signature)
+        try:
+            alg, sig_raw = rr.string(), rr.string()
+        except Exception:
+            return False
+        if alg != b"ssh-ed25519":
+            return False
+        r2 = W.Reader(sig_key_blob)
+        r2.string()
+        pub = r2.string()
+        try:
+            Ed25519PublicKey.from_public_bytes(pub).verify(sig_raw, signed)
+            return True
+        except Exception:
+            return False
+    if ca_type in ("ssh-mldsa44-ed25519",):
+        try:
+            inner = W.Reader(sig_key_blob)
+            inner.string()
+            ca_pub = inner.string()
+            if len(ca_pub) != ML.PK_LEN:
+                return False
+            ca_blob = W.enc_string(b"ssh-mldsa44-ed25519") + W.enc_string(ca_pub)
+            return ML.verify_nested(ca_blob, signed, signature)
+        except Exception:
+            return False
+    # ECDSA/RSA CAs: signature has the same nested shape as hostkeys.
+    rr = W.Reader(signature)
+    try:
+        outer_alg = rr.string().decode()
+    except Exception:
+        return False
+    host_alg = outer_alg if ca_type == "ssh-rsa" else ca_type
+    return HK.verify_host_signature(sig_key_blob, host_alg, signed, signature)
+
+
+def verify_cert(blob: bytes, *, expected_principal: str, is_host: bool, ca_blobs: list[bytes], now: int | None = None) -> dict:
+    """Full verification. Returns the parsed cert or raises CertError."""
+    c = parse_cert(blob)
+    want_role = CERT_TYPE_HOST if is_host else CERT_TYPE_USER
+    if c["role"] != want_role:
+        raise CertError(f"role {c['role']}, expected {want_role}")
+    if c["valid_after"] > c["valid_before"]:
+        raise CertError("certificate has inverted validity interval")
+    t = now if now is not None else int(time.time())
+    if not (c["valid_after"] <= t <= c["valid_before"]):
+        raise CertError("certificate outside validity period")
+    if expected_principal not in c["principals"]:
+        raise CertError(f"principal {expected_principal!r} not in {c['principals']}")
+    unknown_crit = set(c["critical"]) - KNOWN_CRITICAL
+    if unknown_crit:
+        raise CertError(f"unknown critical options (REJECT): {sorted(unknown_crit)}")
+    if "verify-required" in c["critical"]:
+        raise CertError("verify-required needs a security-key touch, unsupported")
+    if c["sig_key"] not in ca_blobs:
+        raise CertError("certificate CA not trusted (@cert-authority)")
+    if not _ca_verify_signed(c["signed_data"], c["sig_key"], c["signature"]):
+        raise CertError("CA signature mismatch")
+    return c
+
+
+def load_ca_keys(known_hosts, host: str, port: int = 22) -> list[bytes]:
+    """
+     CA blobs from @cert-authority lines matching host (fnmatch *?).
+
+     Accepts one path or many (mirrors hostcheck's UserKnownHostsFile
+     lists). Malformed lines are skipped, never fatal: a broken local
+     file must not crash host verification (it just yields no CAs, then
+     strict fails closed). Non-22 ports also match [host]:port patterns
+     like OpenSSH. Hashed |1| patterns match like plain ones.
+    """
+    from ccssh import hostcheck as _HC
+    paths = [known_hosts] if isinstance(known_hosts, str) else list(known_hosts or [])
+    out: list[bytes] = []
+    for kh in paths:
+        if kh == "/dev/null" or os.path.basename(os.path.expanduser(kh)).lower() == "none":
+            continue
+        try:
+            if os.path.getsize(os.path.expanduser(kh)) > _HC.MAX_KNOWN_HOSTS_SIZE:
+                continue
+            with open(os.path.expanduser(kh), encoding="utf-8") as f:
+                lines = f.readlines()
+            if len(lines) > _HC.MAX_KNOWN_HOSTS_LINES:
+                continue
+        except OSError:
+            continue
+        cands = [host] if port == 22 else [host, f"[{host}]:{port}"]
+        for ln in lines:
+            ln = ln.strip()
+            if not ln.startswith("@cert-authority"):
+                continue
+            parts = ln.split()
+            if len(parts) < 4:
+                continue
+            patterns, b64 = parts[1], parts[3] # [2] is the key-type column (informational)
+            try:
+                blob = base64.b64decode(b64, validate=True)
+            except Exception:
+                continue
+            matched = False
+            for c in cands:
+                for pat in patterns.split(","):
+                    if _match_host_ci(pat.strip(), c, host, port):
+                        matched = True
+                        break
+                if matched:
+                    break
+            if matched:
+                out.append(blob)
+    return out
+
+
+def _match_host_ci(pat: str, cand: str, host: str, port: int) -> bool:
+    """
+      Host pattern match: hashed |1| entries via hostcheck, plain/glob
+      entries case-insensitively (DNS names are case-insensitive).
+    """
+    from ccssh import hostcheck as _HC
+    if pat.startswith("|1|"):
+        return _HC._match_host(pat, host, port)
+    return fnmatch.fnmatchcase(cand.lower(), pat.lower())
+
+
+def build_cert(*, keytype: str, pub_fields: bytes, serial: int = 1, role: int = CERT_TYPE_HOST, key_id: bytes = b"test", principals: str | list[str] = "host.example.com", valid_after: int = 0, valid_before: int = 0xFFFFFFFFFFFFFFFF, critical: bytes = b"", extensions: bytes = b"", ca_priv=None, nonce: bytes | None = None) -> bytes:
+    """Assemble and CA-sign a certificate (for tests). pub_fields pre-encoded."""
+    nonce = os.urandom(32) if nonce is None else nonce
+    if isinstance(principals, str):
+        principals = [principals]
+    princ_blob = b"".join(W.enc_string(p.encode()) for p in principals)
+    body = (W.enc_string(keytype.encode())
+            + W.enc_string(nonce)
+            + pub_fields
+            + W.enc_u64(serial)
+            + W.enc_u32(role)
+            + W.enc_string(key_id)
+            + W.enc_string(princ_blob)
+            + W.enc_u64(valid_after)
+            + W.enc_u64(valid_before)
+            + W.enc_string(critical)
+            + W.enc_string(extensions)
+            + W.enc_string(b""))
+    if isinstance(ca_priv, Ed25519PrivateKey):
+        ca_pub = ca_priv.public_key().public_bytes_raw()
+        sig_key = W.enc_string(b"ssh-ed25519") + W.enc_string(ca_pub)
+        sig_key_field = W.enc_string(sig_key)
+        sig_raw = ca_priv.sign(body + sig_key_field)
+        sig = W.enc_string(b"ssh-ed25519") + W.enc_string(sig_raw)
+    elif type(ca_priv).__name__ == "KeyPair":
+        sig_key = ca_priv.public_blob()
+        sig_key_field = W.enc_string(sig_key)
+        sig = ca_priv.sign_nested(body + sig_key_field)
+    else:
+        raise CertError("build_cert supports Ed25519 and mldsa CA keys")
+    return body + sig_key_field + W.enc_string(sig)

ccssh/chacha.py

@@ -0,0 +1,117 @@
+"""
+ chacha20-poly1305@openssh.com (IETF draft-ietf-sshm-chacha20-poly1305).
+
+ Bernstein's original ChaCha20 (8-byte nonce, 64-bit counter) combined with
+ Poly1305 into the SSH AEAD. Layout (K_1 = first 32 key bytes for payload and
+ the Poly1305 one-time key, K_2 = second 32 for the length field):
+
+  enc_length  = packet_length XOR ChaCha(K_2, counter=0, nonce=seq)[:4]
+  enc_payload = payload       XOR ChaCha(K_1, counter=1.., nonce=seq)
+  poly_key    = ChaCha(K_1, counter=0, nonce=seq)[:32]
+  tag         = Poly1305(poly_key, enc_length || enc_payload)
+
+ The raw ChaCha block function is OpenSSL's (via `cryptography`), which is
+ byte-identical to the original for these parameters: original state words
+ x12=ctr_lo, x13=ctr_hi, x14/x15=nonce map onto OpenSSL's IV layout of
+ LE32(counter) || LE32(counter_hi) || nonce8. Verified against the
+ independent pure-Python reference and the draft section 8 test vector,
+ plus live sessions against OpenSSH.
+"""
+from __future__ import annotations
+import hmac as pyhmac
+import struct
+
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms
+from cryptography.hazmat.primitives.poly1305 import Poly1305
+
+from ccssh.crypto import kdf, HASH_sha256
+
+
+def _xor(a: bytes, b: bytes) -> bytes:
+    if len(a) != len(b):
+        raise ValueError("xor inputs must have equal length")
+    out = bytearray(len(a))
+    mv_a, mv_b = memoryview(a), memoryview(b)
+    for i in range(len(a)):
+        out[i] = mv_a[i] ^ mv_b[i]
+    return bytes(out)
+
+
+def keystream(key32: bytes, counter0: int, nonce8: bytes, nbytes: int) -> bytes:
+    """
+     ChaCha keystream for consecutive block counters starting at counter0.
+
+     A single OpenSSL call covers the whole span (the counter advances
+     internally), so this is fast even for tens of kilobytes.
+    """
+    if len(key32) != 32 or len(nonce8) != 8:
+        raise ValueError("key must be 32 bytes, nonce 8 bytes")
+    if not 0 <= counter0 < 2**64:
+        raise ValueError("counter out of 64-bit range")
+    iv = struct.pack("<I", counter0 & 0xFFFFFFFF) + struct.pack("<I", counter0 >> 32) + nonce8
+    enc = Cipher(algorithms.ChaCha20(key32, iv), mode=None).encryptor()
+    return enc.update(b"\x00" * nbytes) + enc.finalize()
+
+
+def chacha_block(key32: bytes, counter: int, nonce8: bytes) -> bytes:
+    """One 64-byte keystream block (convenience wrapper over keystream)."""
+    return keystream(key32, counter, nonce8, 64)
+
+
+class ChachaSshCtx:
+    """One direction. Takes the 64-byte KDF key material (K_1 || K_2)."""
+
+    def __init__(self, key64: bytes):
+        if len(key64) != 64:
+            raise ValueError("key material must be 64 bytes")
+        self.k1, self.k2 = key64[:32], key64[32:]
+
+    def seal(self, seq: int, packet_len: bytes, payload_block: bytes) -> bytes:
+        """
+         packet_len: 4 cleartext length bytes; payload_block holds
+         padding_length || payload || padding. Returns the full wire packet.
+        """
+        if not 0 <= seq < 2**32:
+            raise ValueError("chacha sequence exhausted: rekey required")
+        nonce = struct.pack(">Q", seq)
+        enc_len = _xor(packet_len, keystream(self.k2, 0, nonce, 4))
+        enc_pay = _xor(payload_block, keystream(self.k1, 1, nonce, len(payload_block)))
+        polykey = keystream(self.k1, 0, nonce, 32)
+        tag = Poly1305(polykey)
+        tag.update(enc_len + enc_pay)
+        return enc_len + enc_pay + tag.finalize()
+
+    def open(self, seq: int, wire: bytes) -> tuple[bytes, bytes]:
+        """Returns (packet_len, payload_block). Raises on bad MAC."""
+        if not 0 <= seq < 2**32:
+            raise ValueError("chacha sequence exhausted: rekey required")
+        if len(wire) < 4 + 1 + 16:
+            raise ValueError("wire packet too short")
+        nonce = struct.pack(">Q", seq)
+        enc_len, rest = wire[:4], wire[4:]
+        enc_pay, tag_recv = rest[:-16], rest[-16:]
+        polykey = keystream(self.k1, 0, nonce, 32)
+        tag = Poly1305(polykey)
+        tag.update(enc_len + enc_pay)
+        if not pyhmac.compare_digest(tag.finalize(), tag_recv):
+            raise ValueError("Poly1305 mismatch")
+        packet_len = _xor(enc_len, keystream(self.k2, 0, nonce, 4))
+        payload_block = _xor(enc_pay, keystream(self.k1, 1, nonce, len(enc_pay)))
+        return packet_len, payload_block
+
+    def decrypt_length(self, seq: int, enc_len: bytes) -> bytes:
+        """Decrypt the 4 length bytes without touching payload state (stateless)."""
+        if not 0 <= seq < 2**32:
+            raise ValueError("chacha sequence exhausted: rekey required")
+        return _xor(enc_len, keystream(self.k2, 0, struct.pack(">Q", seq), 4))
+
+
+def derive_chacha_keys(K_encoded: bytes, H: bytes, session_id: bytes, hashfn=None) -> dict[str, bytes]:
+    # Production callers must pass the KEX hash; fallback kept for tests.
+    if hashfn is None:
+        hashfn = HASH_sha256
+    hf = hashfn
+    return {
+        "enc_c2s": kdf(hf, K_encoded, H, session_id, b"C", 64),
+        "enc_s2c": kdf(hf, K_encoded, H, session_id, b"D", 64),
+    }

ccssh/channel.py

@@ -0,0 +1,124 @@
+"""
+ Channel message codecs, RFC 4254: session open, exec/subsystem requests,
+ direct-tcpip open, data, window adjust, close.
+"""
+from __future__ import annotations
+
+from ccssh import wire as W
+
+MSG_CHANNEL_OPEN = 90
+MSG_CHANNEL_OPEN_CONFIRM = 91
+MSG_CHANNEL_OPEN_FAILURE = 92
+MSG_WINDOW_ADJUST = 93
+MSG_CHANNEL_DATA = 94
+MSG_CHANNEL_EXTENDED_DATA = 95
+MSG_CHANNEL_EOF = 96
+MSG_CHANNEL_CLOSE = 97
+MSG_CHANNEL_REQUEST = 98
+MSG_CHANNEL_SUCCESS = 99
+MSG_CHANNEL_FAILURE = 100
+
+WINDOW = 2 * 1024 * 1024
+MAXPKT = 32768
+# Send WINDOW_ADJUST after consuming this many channel bytes (half a window).
+WINDOW_THRESHOLD = 1024 * 1024
+# Per-channel relay backlog cap (forwarders, jump sockets): a slow reader
+# must fail its channel, never OOM the process.
+MAX_BUFFER = 16 * 1024 * 1024
+
+
+def enc_open_session(sender: int) -> bytes:
+    return (bytes([MSG_CHANNEL_OPEN]) + W.enc_string(b"session") + W.enc_u32(sender) + W.enc_u32(WINDOW) + W.enc_u32(MAXPKT))
+
+
+def enc_exec(recipient: int, command: str, *, want_reply: bool = True) -> bytes:
+    return (bytes([MSG_CHANNEL_REQUEST])
+            + W.enc_u32(recipient)
+            + W.enc_string(b"exec")
+            + W.enc_bool(want_reply)
+            + W.enc_string(command.encode()))
+
+
+def enc_subsystem(recipient: int, name: str = "sftp", *, want_reply: bool = True) -> bytes:
+    return (bytes([MSG_CHANNEL_REQUEST])
+            + W.enc_u32(recipient)
+            + W.enc_string(b"subsystem")
+            + W.enc_bool(want_reply)
+            + W.enc_string(name.encode()))
+
+
+def enc_pty_req(recipient: int, term: str = "xterm", cols: int = 80, rows: int = 24, width_px: int = 0, height_px: int = 0, modes: bytes = b"", *, want_reply: bool = True) -> bytes:
+    """RFC 4254 section 6.2 pty-req. Empty modes = all opcodes stay default."""
+    return (bytes([MSG_CHANNEL_REQUEST])
+            + W.enc_u32(recipient)
+            + W.enc_string(b"pty-req")
+            + W.enc_bool(want_reply)
+            + W.enc_string(term.encode())
+            + W.enc_u32(cols)
+            + W.enc_u32(rows)
+            + W.enc_u32(width_px)
+            + W.enc_u32(height_px)
+            + W.enc_string(modes))
+
+
+def enc_shell(recipient: int, *, want_reply: bool = True) -> bytes:
+    """RFC 4254 section 6.5 shell request."""
+    return (bytes([MSG_CHANNEL_REQUEST])
+            + W.enc_u32(recipient)
+            + W.enc_string(b"shell")
+            + W.enc_bool(want_reply))
+
+
+def enc_window_change(recipient: int, cols: int, rows: int, width_px: int = 0, height_px: int = 0) -> bytes:
+    """RFC 4254 section 6.7. Always want_reply=False (no reply is sent)."""
+    return (bytes([MSG_CHANNEL_REQUEST])
+            + W.enc_u32(recipient)
+            + W.enc_string(b"window-change")
+            + W.enc_bool(False)
+            + W.enc_u32(cols)
+            + W.enc_u32(rows)
+            + W.enc_u32(width_px)
+            + W.enc_u32(height_px))
+
+
+def enc_eof(recipient: int) -> bytes:
+    """RFC 4254 section 5.3: no more data will be sent (stdin EOF)."""
+    return bytes([MSG_CHANNEL_EOF]) + W.enc_u32(recipient)
+
+
+def enc_open_direct_tcpip(sender: int, host: str, port: int, orig_host: str = "127.0.0.1", orig_port: int = 0) -> bytes:
+    return (bytes([MSG_CHANNEL_OPEN])
+            + W.enc_string(b"direct-tcpip")
+            + W.enc_u32(sender)
+            + W.enc_u32(WINDOW)
+            + W.enc_u32(MAXPKT)
+            + W.enc_string(host.encode())
+            + W.enc_u32(port)
+            + W.enc_string(orig_host.encode())
+            + W.enc_u32(orig_port))
+
+
+def enc_data(recipient: int, data: bytes) -> bytes:
+    if len(data) > MAXPKT:
+        raise ValueError(f"channel data chunk exceeds MAXPKT ({len(data)} > {MAXPKT})")
+    return bytes([MSG_CHANNEL_DATA]) + W.enc_u32(recipient) + W.enc_string(data)
+
+
+def enc_window_adjust(recipient: int, delta: int) -> bytes:
+    if not 0 < delta < 2**32:
+        raise ValueError(f"window adjust delta out of range: {delta}")
+    return bytes([MSG_WINDOW_ADJUST]) + W.enc_u32(recipient) + W.enc_u32(delta)
+
+
+def check_window(window: int, delta: int) -> int:
+    """Add a WINDOW_ADJUST credit, enforcing RFC 4254 section 5.2 limits."""
+    if not 0 < delta < 2**32:
+        raise ValueError(f"bad window increment {delta}")
+    new = window + delta
+    if new > 0xFFFFFFFF:
+        raise ValueError("channel window exceeds 2^32-1")
+    return new
+
+
+def enc_close(recipient: int) -> bytes:
+    return bytes([MSG_CHANNEL_CLOSE]) + W.enc_u32(recipient)